CONNECTION_HANDLE_TYPE_NONE = HANDLE_TYPE_NONE
CONNECTION_HANDLE_TYPE_CONTACT = HANDLE_TYPE_CONTACT
CONNECTION_HANDLE_TYPE_ROOM = HANDLE_TYPE_ROOM
CONNECTION_HANDLE_TYPE_LIST = HANDLE_TYPE_LIST
CONNECTION_HANDLE_TYPE_USER_CONTACT_GROUP = HANDLE_TYPE_GROUP CONN_MGR_INTERFACE = CONNECTION_MANAGER
CONN_INTERFACE = CONNECTION
CHANNEL_INTERFACE = CHANNEL
CHANNEL_HANDLER_INTERFACE = CHANNEL_HANDLER
CONN_INTERFACE_ALIASING = CONNECTION_INTERFACE_ALIASING
CONN_INTERFACE_AVATARS = CONNECTION_INTERFACE_AVATARS
CONN_INTERFACE_CAPABILITIES = CONNECTION_INTERFACE_CAPABILITIES
CONN_INTERFACE_PRESENCE = CONNECTION_INTERFACE_PRESENCE
CONN_INTERFACE_RENAMING = CONNECTION_INTERFACE_RENAMING class Handle(object):
    def __init__(self, id, handle_type, name):
        self._id = id
        self._type = handle_type
        self._name = name

    def get_id(self):
        return self._id

    def __hash__(self):
        return self._id.__hash__()

    def __int__(self):
        return int(self._id)

    def __long__(self):
        return int(self._id)

    def get_type(self):
        return self._type

    def get_name(self):
        return self._name

    def __eq__(self, other):
        return (int(self) == int(other) and self.get_type() == other.get_type())

    def __ne__(self, other):
        return not self.__eq__(other)

    id = property(get_id)
    type = property(get_type)
    name = property(get_name) class NoneHandle(Handle):
    def __init__(self):
        Handle.__init__(self, 0, HANDLE_TYPE_NONE, '') class DBusProperties(dbus.service.Interface):
    def __init__(self):
        if not getattr(self, '_interfaces', None):
            self._interfaces = set()

        self._interfaces.add(dbus.PROPERTIES_IFACE)

        if not getattr(self, '_immutable_properties', None):
            self._immutable_properties = dict()

        if not getattr(self, '_prop_getters', None):
            self._prop_getters = {}
            self._prop_setters = {}

    def _implement_property_get(self, iface, dict):
        self._prop_getters.setdefault(iface, {}).update(dict)

    def _implement_property_set(self, iface, dict):
        self._prop_setters.setdefault(iface, {}).update(dict)

    def _add_immutable_properties(self, props):
        self._immutable_properties.update(props)

    def get_immutable_properties(self):
        props = dict()
        for prop, iface in list(self._immutable_properties.items()):
            props[iface + '.' + prop] = self._prop_getters[iface][prop]()
        return props

    @dbus.service.method(dbus_interface=dbus.PROPERTIES_IFACE, in_signature='ss', out_signature='v')
    def Get(self, interface_name, property_name):
        if interface_name in self._prop_getters \
            and property_name in self._prop_getters[interface_name]:
                return self._prop_getters[interface_name][property_name]()
        else:
            raise telepathy.errors.InvalidArgument()

    @dbus.service.method(dbus_interface=dbus.PROPERTIES_IFACE, in_signature='ssv', out_signature='')
    def Set(self, interface_name, property_name, value):
        if interface_name in self._prop_setters \
            and property_name in self._prop_setters[interface_name]:
                self._prop_setters[interface_name][property_name](value)
        else:
            raise telepathy.errors.PermissionDenied()

    @dbus.service.method(dbus_interface=dbus.PROPERTIES_IFACE, in_signature='s', out_signature='a{sv}')
    def GetAll(self, interface_name):
        if interface_name in self._prop_getters:
            r = {}
            for k, v in list(self._prop_getters[interface_name].items()):
                r[k] = v()
            return r
        else:
            raise telepathy.errors.InvalidArgument() class Connection(dbus.service.Object):
    """\
      This models a connection to a single user account on a communication
        service. Its basic capability is to provide the facility to request and
        receive channels of differing types (such as text channels or streaming
        media channels) which are used to carry out further communication.

      In order to allow Connection objects to be discovered by new clients,
        the object path and well-known bus name MUST be of the form
        /org/freedesktop/Telepathy/Connection/cmname/proto/account
        and
        org.freedesktop.Telepathy.Connection.cmname.proto.account
        where:

      
        cmname is the same
          Connection_Manager_Name that appears
          in the connection manager's object path and well-known bus name
        proto is the Protocol name as seen in
          ListProtocols,
          but with "-" replaced with "_" to get a valid
          object path/bus name
        account is some non-empty sequence of ASCII letters,
          digits and underscores not starting with a digit
      

      account SHOULD be formed such that any valid distinct
        connection instance on this protocol has a distinct name. This
        might be formed by including the server name followed by the user
        name (escaped via some suitable mechanism like telepathy-glib's
        tp_escape_as_identifier() function to preserve uniqueness); on
        protocols where connecting multiple times is permissable, a
        per-connection identifier might be necessary to ensure
        uniqueness.

      Clients MAY parse the object path to determine the connection
        manager name and the protocol, but MUST NOT attempt to parse the
        account part. Connection managers MAY use any unique string
        for this part.

    As well as the methods and signatures below, arbitrary interfaces may be
    provided by the Connection object to represent extra connection-wide
    functionality, such as the Connection.Interface.SimplePresence for
    receiving and
    reporting presence information, and Connection.Interface.Aliasing for
    connections where contacts may set and change an alias for themselves.
    These interfaces can be discovered using the
    GetInterfaces method.

    Contacts, rooms, and server-stored lists (such as subscribed contacts,
    block lists, or allow lists) on a service are all represented by
    immutable handles, which are unsigned non-zero integers which are
    valid only for the lifetime of the connection object, and are used
    throughout the protocol where these entities are represented, allowing
    simple testing of equality within clients.

    Zero as a handle value is sometimes used as a "null" value to mean
    the absence of a contact, room, etc.

    Handles have per-type uniqueness, meaning that
    every (handle type, handle number) tuple is guaranteed to be unique within
    a connection and that a handle alone (without its type) is meaningless or
    ambiguous. Connection manager implementations should reference count these
    handles to determine if they are in use either by any active clients or any
    open channels, and may deallocate them when this ceases to be true. Clients
    may request handles of a given type and identifier with the
    RequestHandles method, inspect the entity
    identifier with the InspectHandles
    method, keep handles from being released with
    HoldHandles, and notify that they are no
    longer storing handles with
    ReleaseHandles.
    """

    @dbus.service.method('org.freedesktop.Telepathy.Connection', in_signature='', out_signature='')
    def Connect(self):
        """
        Request that the connection be established. This will be done
          asynchronously and errors will be returned by emitting
          StatusChanged signals.

        Calling this method on a Connection that is already connecting
          or connected is allowed, and has no effect.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection', in_signature='', out_signature='')
    def Disconnect(self):
        """
        Request that the connection be closed. This closes the connection if
        it's not already in DISCONNECTED state, and destroys the connection
        object.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection', in_signature='', out_signature='as')
    def GetInterfaces(self):
        """
        Returns the set of optional interfaces supported by this
          connection. See Interfaces for more
          details.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection', in_signature='', out_signature='s')
    def GetProtocol(self):
        """
        Get the protocol this connection is using.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection', in_signature='', out_signature='u')
    def GetSelfHandle(self):
        """
        Returns the value of the SelfHandle property. Change notification
        is via the SelfHandleChanged signal.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection', in_signature='', out_signature='u')
    def GetStatus(self):
        """
        Get the current status as defined in the
        StatusChanged signal.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection', in_signature='uau', out_signature='')
    def HoldHandles(self, Handle_Type, Handles):
        """
        If HasImmortalHandles is true,
          which SHOULD always be the case in this version of telepathy-spec,
          this method does nothing and returns successfully, unless
          the given handle type or any of the given handles is invalid.

        In older connection managers, this method
        notifies the connection manger that your client is holding a copy
        of handles which may not be in use in any existing channel or
        list, and were not obtained by using the
        RequestHandles method. For
        example, a handle observed in an emitted signal, or displayed
        somewhere in the UI that is not associated with a channel. The
        connection manager must not deallocate a handle where any clients
        have used this method to indicate it is in use until the
        ReleaseHandles
        method is called, or the clients disappear from the bus.

        Note that HoldHandles is idempotent - calling it multiple times
          is equivalent to calling it once. If a handle is "referenced" by
          several components which share a D-Bus unique name, the client
          should perform reference counting internally, and only call
          ReleaseHandles when none of the cooperating components need the
          handle any longer.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection', in_signature='uau', out_signature='as')
    def InspectHandles(self, Handle_Type, Handles):
        """
        Return a string representation for a number of handles of a given
        type.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection', in_signature='', out_signature='a(osuu)')
    def ListChannels(self):
        """
        List all the channels which currently exist on this connection.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection', in_signature='uau', out_signature='')
    def ReleaseHandles(self, Handle_Type, Handles):
        """
        If HasImmortalHandles is true,
          which SHOULD always be the case in this version of telepathy-spec,
          this method does nothing and returns successfully, unless
          the given handle type or any of the given handles is invalid.

        In older connection managers, this method
        explicitly notifies the connection manager that your client is no
        longer holding any references to the given handles, and that they
        may be deallocated if they are not held by any other clients or
        referenced by any existing channels. See
        HoldHandles for notes.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection', in_signature='suub', out_signature='o')
    def RequestChannel(self, Type, Handle_Type, Handle, Suppress_Handler):
        """
        Request a channel satisfying the specified type and communicating
          with the contact, room, list etc. indicated by the given
          handle_type and handle. The handle_type and handle may both be
          zero to request the creation of a new, empty channel, which may
          or may not be possible, depending on the protocol and channel
          type.

        On success, the returned channel will always be of the requested
          type (i.e. implement the requested channel-type interface).

        If a new, empty channel is requested, on success the returned
          channel will always be an "anonymous" channel for which the type
          and handle are both zero.

        If a channel to a contact, room etc. is requested, on success, the
          returned channel may either be a new or existing channel to
          the requested entity (i.e. its
          TargetHandleType
          and TargetHandle
          properties are the
          requested handle type and handle), or a newly created "anonymous"
          channel associated with the requested handle in some
          implementation-specific way.

        For example, for a contact handle, the returned channel
          might be "anonymous", but implement the groups interface and have
          the requested contact already present among the members.

        If the request cannot be satisfied, an error is raised and no
          channel is created.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection', in_signature='uas', out_signature='au')
    def RequestHandles(self, Handle_Type, Identifiers):
        """
        Request several handles from the connection manager which represent a
          number of contacts, rooms or server-stored lists on the service.

        If HasImmortalHandles is true,
          which SHOULD always be the case in this version of telepathy-spec,
          the handles remain valid until the connection disconnects.

        The implementation of this method in older connection managers
        must record that these handles are in use by the
        client who invokes this method, and must not deallocate the handles
        until the client disconnects from the bus or calls the
        ReleaseHandles
        method. Where the identifier refers to an entity that already has a
        handle in this connection manager, this handle should be returned
        instead. The handle number 0 must not be returned by the connection
        manager.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection', in_signature='as', out_signature='')
    def AddClientInterest(self, Tokens):
        """
        Register a client's interest in notifications related to one or
          more interfaces.

        Groups of notifications are identified by a token which is either
          a D-Bus interface name, or a string that starts with a D-Bus
          interface name. The meaning of each token is given by that D-Bus
          interface, which MUST define it in its documentation.

        
          Initially, all interests are in entire interface, but allowing
            other strings allows subscription to part of an interface; for
            instance, an interest in ...MailNotification/count could track
            the number of messages without caring about their detailed
            content.
        

        For each token with which this method interacts, the
          Connection tracks an "interest count" (like a reference count) for
          each unique bus name that has called this method. When a client
          calls this method, for each token, the interest count for its
          unique bus name is incremented; when
          RemoveClientInterest is called,
          all interest counts for that unique bus name are decremented.
          If the unique bus name leaves the bus (for instance, if the
          client crashes or exits), all interest counts for that unique bus
          name are set to zero.

        The Connection can then use these reference counts to
          avoid subscribing to protocol-level notifications unless at least
          one client has a non-zero interest count for the relevant
          token.

        
          This method exists to reduce memory and network overhead when
            there is no active subscription.

          One situation where this is useful is Location: on XMPP, location updates are received
            over PEP. If the Connection advertises the
            geoloc+notify capability, it will be sent location
            updates for all contacts. To avoid consuming resources for this,
            the connection should avoid advertising that capability until
            a client has expressed an interest in contacts' locations.

          Another example of a protocol that benefits from this method is
            the Google XMPP Mail Notification extension, which can be used
            to implement MailNotification. In this protocol, the CM
            receives a notification that something has changed, but to get
            more information, the CM must request this information. Knowing
            that nobody is currently interested in this information, the CM
            can avoid generating useless network traffic. Similarly, the CM
            may free the list of unread messages to reduce memory overhead.
        

        If this method is called for an interface that might require
          protocol-level subscription, but the connection cannot set up
          that subscription yet (for instance because the
          Status is not Connected yet), the
          Connection MUST remember the client's interest, and attempt to
          subscribe to the appropriate protocol feature when this becomes
          possible.

        Clients MAY ignore any errors raised by this method; it is intended
          to be called with the reply ignored.

        
          The only reason it could fail is if it's unimplemented, in which
            case the only thing the client can usefully do is to proceed as if
            it had succeeded.
        
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection', in_signature='as', out_signature='')
    def RemoveClientInterest(self, Tokens):
        """
        Release an interest registered using
          AddClientInterest. See that
          method's documentation for details.

        Clients MAY ignore any errors raised by this method; it is intended
          to be called with the reply ignored.

        
          The only reasons it could fail are if it's unimplemented, or if
            the client's reference-counting is wrong and it has tried to
            remove a client interest that it did not add. In both cases,
            there's nothing the client could do about it.
        
      
        """
        raise NotImplementedError
  
    @dbus.service.signal('org.freedesktop.Telepathy.Connection', signature='u')
    def SelfHandleChanged(self, Self_Handle):
        """
        Emitted whenever the SelfHandle property
        changes. If the connection
        is not yet in the CONNECTED state, this signal is not guaranteed
        to be emitted.
      
        """
        pass
  
    @dbus.service.signal('org.freedesktop.Telepathy.Connection', signature='osuub')
    def NewChannel(self, Object_Path, Channel_Type, Handle_Type, Handle, Suppress_Handler):
        """
        Emitted when a new Channel object is created, either through user
        request or incoming information from the service.
      
        """
        pass
  
    @dbus.service.signal('org.freedesktop.Telepathy.Connection', signature='sa{sv}')
    def ConnectionError(self, Error, Details):
        """
        Emitted when an error occurs that renders this connection unusable.
        

        Whenever this signal is emitted, it MUST immediately be followed by
          a StatusChanged signal with status
          Connection_Status_Disconnected and an appropriate reason
          code.

        Connection managers SHOULD emit this signal on disconnection, but
          need not do so. Clients MUST support connection managers that emit
          StatusChanged(Disconnected, ...) without first emitting
          ConnectionError.

        
          This signal provides additional information about the reason
            for disconnection. The reason for connection is always
            straightforward - it was requested - so it does not need further
            explanation. However, on errors, it can be useful to provide
            additional information.

          The Connection_Status_Reason is not given
            here, since it will be signalled in
            StatusChanged. A reasonable client
            implementation would be to store the information given by this
            signal until StatusChanged is received, at which point the
            information given by this signal can be used to supplement the
            StatusChanged signal.
        
      
        """
        pass
  
    @dbus.service.signal('org.freedesktop.Telepathy.Connection', signature='uu')
    def StatusChanged(self, Status, Reason):
        """
        Emitted when the status of the connection changes.  All states and
        reasons have numerical values, as defined in ConnectionStatus
        and ConnectionStatusReason.
      
        """
        pass class ConnectionInterfaceAliasing(dbus.service.Interface):
    """\
      An interface on connections to support protocols where contacts have an
    alias which they can change at will. Provides a method for the user to set
    their own alias, and a signal which should be emitted when a contact's
    alias is changed or first discovered.

    On connections where the user is allowed to set aliases for contacts and
    store them on the server, the GetAliasFlags
    method will have the CONNECTION_ALIAS_FLAG_USER_SET flag set, and the
    SetAliases method may be called on contact
    handles other than the user themselves.

    Aliases are intended to be used as the main displayed name for the
    contact, where available.
    """

    def __init__(self):
        self._interfaces.add('org.freedesktop.Telepathy.Connection.Interface.Aliasing')

    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Aliasing', in_signature='', out_signature='u')
    def GetAliasFlags(self):
        """
        Return a bitwise OR of flags detailing the behaviour of aliases on this
        connection.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Aliasing', in_signature='au', out_signature='as')
    def RequestAliases(self, Contacts):
        """
        Request the value of several contacts' aliases at once.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Aliasing', in_signature='au', out_signature='a{us}')
    def GetAliases(self, Contacts):
        """
        Request the value of several contacts' aliases at once. This SHOULD
        only return cached aliases, falling back on the contact identifier
        (i.e. the string corresponding to the handle) if none is present. Also
        if there was no cached alias, a request SHOULD be started of which the
        result is later signalled by
        AliasesChanged.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Aliasing', in_signature='a{us}', out_signature='')
    def SetAliases(self, Aliases):
        """
        Request that the alias of the given contact be changed. Success will be
        indicated by emitting an AliasesChanged
        signal. On connections where the CONNECTION_ALIAS_FLAG_USER_SET flag is
        not set, this method will only ever succeed if the contact is the
        user's own handle (as returned by Connection.GetSelfHandle).
      
        """
        raise NotImplementedError
  
    @dbus.service.signal('org.freedesktop.Telepathy.Connection.Interface.Aliasing', signature='a(us)')
    def AliasesChanged(self, Aliases):
        """
        Signal emitted when a contact's alias (or that of the user) is changed.
      
        """
        pass class ConnectionInterfaceAvatars(dbus.service.Interface):
    """\
      An interface for requesting avatars for contacts on a given connection,
    receiving notification when avatars are changed, and publishing your own
    avatar.

    Avatars are identified by a string, the Avatar_Token,
    which represents a particular avatar. Tokens MUST be chosen by the
    connection manager in such a way that the triple
    (Connection_Manager_Name, Protocol,
    Avatar_Token) uniquely identifies an avatar.
    An empty token means that an avatar has not been set for this contact, and
    a changed token implies the contact's avatar has changed, but the strings
    should otherwise be considered opaque by clients.

    A client should use GetKnownAvatarTokens
    to request the tokens for the
    avatars of all the contacts it is interested in when it connects. The
    avatars can then be requested using
    RequestAvatars for the contacts.  Clients
    should bind to the AvatarUpdated signal and
    request a new copy of
    the avatar when a contacts' avatar token changes. Clients should cache the
    token and data of each contact's avatar between connections, to avoid
    repeatedly retrieving the same avatar.

    To publish an avatar, a client should use
    SetAvatar to provide an image which meets
    the requirements returned by the
    GetAvatarRequirements
    function. On some protocols the avatar is stored on the server, so setting
    the avatar is persistent, but on others it is transferred via a peer to
    peer mechanism, so needs to be set every connection. Hence, on every
    connection, clients should inspect the avatar token of the connection's
    self handle using GetKnownAvatarTokens; if
    the self handle is not in the
    returned map, the client should re-set the avatar. If the self handle's
    avatar token is known, but the avatar has been changed locally since the
    last connection, the client should upload the new avatar; if the avatar has
    not changed locally, then the client should download the avatar from the
    server if its token differs from the that of the local avatar.

    To remove the published avatar on protocols which have persistent avatars,
    a client should use the ClearAvatar method.
    This method can safely be used even if there is no avatar for this
    connection.
    """

    def __init__(self):
        self._interfaces.add('org.freedesktop.Telepathy.Connection.Interface.Avatars')

    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Avatars', in_signature='', out_signature='asqqqqu')
    def GetAvatarRequirements(self):
        """
        Get the required format of avatars on this connection.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Avatars', in_signature='au', out_signature='as')
    def GetAvatarTokens(self, Contacts):
        """
        Get the unique tokens for all of the given contacts' avatars.

        Using this method in new Telepathy clients is deprecated; use
        GetKnownAvatarTokens instead.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Avatars', in_signature='au', out_signature='a{us}')
    def GetKnownAvatarTokens(self, Contacts):
        """
        Get the unique tokens for the given contacts' avatars. These tokens
        can be persisted across connections, and should be used by the client
        to check whether the avatars have been updated.  For handles other than
        the self handle, only tokens that are already known are returned; an
        empty token means the given contact has no avatar.  However, a CM must
        always have the tokens for the self handle if one is set (even if it is
        set to no avatar).  On protocols where the avatar does not persist
        between connections, a CM should omit the self handle from the returned
        map until an avatar is explicitly set or cleared.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Avatars', in_signature='u', out_signature='ays')
    def RequestAvatar(self, Contact):
        """
        Request the avatar for a given contact. Using this method in new
        Telepathy clients is deprecated; use RequestAvatars instead.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Avatars', in_signature='au', out_signature='')
    def RequestAvatars(self, Contacts):
        """
        Request avatars for a number of contacts. The
        AvatarRetrieved signal is emitted for
        each avatar retrieved. If the handles are valid but retrieving an
        avatar fails (for any reason, including the contact not having an
        avatar) the AvatarRetrieved signal is not emitted for that contact.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Avatars', in_signature='ays', out_signature='s')
    def SetAvatar(self, Avatar, MIME_Type):
        """
        Set a new avatar image for this connection. The avatar image must
        respect the requirements obtained by
        GetAvatarRequirements.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Avatars', in_signature='', out_signature='')
    def ClearAvatar(self):
        """
        Remove the avatar image for this connection.
      
        """
        raise NotImplementedError
  
    @dbus.service.signal('org.freedesktop.Telepathy.Connection.Interface.Avatars', signature='us')
    def AvatarUpdated(self, Contact, New_Avatar_Token):
        """
        Emitted when the avatar for a contact has been updated, or first
        discovered on this connection. If the token differs from the token
        associated with the client's cached avatar for this contact, the new
        avatar should be requested with
        RequestAvatars.
      
        """
        pass
  
    @dbus.service.signal('org.freedesktop.Telepathy.Connection.Interface.Avatars', signature='usays')
    def AvatarRetrieved(self, Contact, Token, Avatar, Type):
        """
        Emitted when the avatar for a contact has been retrieved.
      
        """
        pass class ConnectionInterfaceCapabilities(dbus.service.Interface):
    """\
      An interface for connections where it is possible to know what channel
        types may be requested before the request is made to the connection
        object. Each capability represents a commitment by the connection
        manager that it will ordinarily be able to create a channel when given
        a request with the given type and handle.

      Capabilities pertain to particular contact handles, and represent
        activities such as having a text chat or a voice call with the user.
        The activities are represented by the D-Bus interface name of the
        channel type for that activity.

      The generic capability flags are defined by
        Connection_Capability_Flags.

      In addition, channel types may have type specific capability flags of
        their own, which are described in the documentation for each channel
        type.

      This interface also provides for user interfaces notifying the
        connection manager of what capabilities to advertise for the user. This
        is done by using the
        AdvertiseCapabilities method, and deals
        with the
        interface names of channel types and the type specific flags pertaining
        to them which are implemented by available client processes.
    """

    def __init__(self):
        self._interfaces.add('org.freedesktop.Telepathy.Connection.Interface.Capabilities')

    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Capabilities', in_signature='a(su)as', out_signature='a(su)')
    def AdvertiseCapabilities(self, Add, Remove):
        """
        Used by user interfaces to indicate which channel types they are able
        to handle on this connection. Because these may be provided by
        different client processes, this method accepts channel types to add
        and remove from the set already advertised on this connection. The type
        of advertised capabilities (create versus invite) is protocol-dependent
        and hence cannot be set by the this method. In the case of a client
        adding an already advertised channel type but with new channel type
        specific flags, the connection manager should simply add the new flags
        to the set of advertised capabilities.

        Upon a successful invocation of this method, the
        CapabilitiesChanged
        signal will be emitted for the user's own handle ( Connection.GetSelfHandle)
        by the connection manager to indicate the changes
        that have been made.  This signal should also be monitored to ensure
        that the set is kept accurate - for example, a client may remove
        capabilities or type specific capability flags when it exits
        which are still provided by another client.

        On connections managed by the ChannelDispatcher,
          this method SHOULD NOT be used by clients other than the
          ChannelDispatcher itself.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Capabilities', in_signature='au', out_signature='a(usuu)')
    def GetCapabilities(self, Handles):
        """
        Returns an array of capabilities for the given contact handles.
      
        """
        raise NotImplementedError
  
    @dbus.service.signal('org.freedesktop.Telepathy.Connection.Interface.Capabilities', signature='a(usuuuu)')
    def CapabilitiesChanged(self, Caps):
        """
        Announce that there has been a change of capabilities on the
          given handle.

        If the handle is zero, the capabilities refer to the connection
          itself, in some poorly defined way. This usage is deprecated and
          clients should ignore it.
      
        """
        pass class ConnectionInterfaceContactCapabilities(dbus.service.Interface):
    """\
      Contact capabilities describe the channel classes which may be
        created with a given contact in advance of attempting to create a
        channel. Each capability represents a commitment by the
        connection manager that it will ordinarily be able to create a channel
        with a contact when given a request with the properties defined by the
        channel class.

      Capabilities pertain to particular contact handles, and represent
        activities such as having a text chat, a voice call with the user or a
        stream tube of a defined type.

      This interface also enables user interfaces to notify the connection
        manager what capabilities to advertise for the user to other contacts.
        This is done by using the
        UpdateCapabilities method.

      
        XMPP is a major user of this interface: XMPP contacts will not,
          in general, be callable using VoIP unless they advertise suitable
          Jingle capabilities.

        Many other protocols also have some concept of capability flags,
          which this interface exposes in a protocol-independent way.
      
    """

    def __init__(self):
        self._interfaces.add('org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities')

    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities', in_signature='a(saa{sv}as)', out_signature='')
    def UpdateCapabilities(self, Handler_Capabilities):
        """
        Alter the connection's advertised capabilities to include
          the intersection of the given clients' capabilities with what the
          connection manager is able to implement.

        On connections managed by the ChannelDispatcher, processes other
          than the ChannelDispatcher SHOULD NOT call this method, and the
          ChannelDispatcher SHOULD use this method to advertise the
          capabilities of all the registered Client.Handler
          implementations.On connections not managed by the ChannelDispatcher,
          clients MAY use this method directly, to indicate the channels they
          will handle and the extra capabilities they have.

        Upon a successful invocation of this method, the connection manager
          will only emit the
          ContactCapabilitiesChanged signal
          for the user's SelfHandle
          if, in the underlying protocol, the new capabilities are distinct
          from the previous state.

        
          The connection manager will essentially intersect the provided
            capabilities and the channel classes it implements. Therefore,
            certain properties which are never fixed for a channel class
            (such as the target handle, or the Parameters property of a tube
            channel) will almost certainly not be advertised.
        

        This method MAY be called on a newly-created connection while it
          is still in the DISCONNECTED state, to request that when the
          connection connects, it will do so with the appropriate
          capabilities. Doing so MUST NOT fail.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities', in_signature='au', out_signature='a{ua(a{sv}as)}')
    def GetContactCapabilities(self, Handles):
        """
        Returns an array of requestable channel classes for the given
          contact handles, representing the channel requests that are
          expected to succeed.
      
        """
        raise NotImplementedError
  
    @dbus.service.signal('org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities', signature='a{ua(a{sv}as)}')
    def ContactCapabilitiesChanged(self, caps):
        """
        Announce that there has been a change of capabilities on the
          given handles. A single signal can be emitted for several
        contacts.

        
          The underlying protocol can get several contacts' capabilities at
            the same time.
        

      
        """
        pass class ConnectionInterfaceRequests(dbus.service.Interface):
    """\
      An enhanced version of the Telepathy connection interface, which can
        represent bundles of channels that should be dispatched together, and
        does not assume any particular properties by which channels are
        uniquely identifiable.

      If this interface is implemented on a connection, then
        NewChannels MUST be emitted for
        all new channels, even those created with RequestChannel.
    """

    def __init__(self):
        self._interfaces.add('org.freedesktop.Telepathy.Connection.Interface.Requests')

    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Requests', in_signature='a{sv}', out_signature='oa{sv}')
    def CreateChannel(self, Request):
        """
        Request that an entirely new channel is created.

        
          There is deliberately no flag corresponding to the
            suppress_handler argument to
            Connection.RequestChannel,
            because passing a FALSE value for that argument is deprecated.
            Requests made using this interface always behave as though
            suppress_handler was TRUE.
        

      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Requests', in_signature='a{sv}', out_signature='boa{sv}')
    def EnsureChannel(self, Request):
        """
        Request that channels are ensured to exist.

        
          The connection manager is in the best position to determine which
            existing channels could satisfy which requests.
        

      
        """
        raise NotImplementedError
  
    @dbus.service.signal('org.freedesktop.Telepathy.Connection.Interface.Requests', signature='a(oa{sv})')
    def NewChannels(self, Channels):
        """
        New channels have been created. The connection manager SHOULD emit
          a single signal for any group of closely related channels that are
          created at the same time, so that the channel dispatcher can try to
          dispatch them to a handler as a unit.

        In particular, if additional channels are created as a side-effect
          of a call to CreateChannel,
          these channels SHOULD appear in the same NewChannels signal as
          the channel that satisfies the request.

        
          Joining a MUC Tube in XMPP requires joining the corresponding
            MUC (chatroom), so a Text
            channel can be created as a side-effect.
        

        Every time NewChannels is emitted, it MUST be followed by
          a Connection.NewChannel
          signal for each channel.

        
          The double signal emission is for the benefit of older Telepathy
            clients, which won't be listening for NewChannels.

          The more informative NewChannels signal comes first so that
            clients that did not examine the connection to find
            out whether Requests is supported will see the more informative
            signal for each channel first, and then ignore the less
            informative signal because it announces a new channel of which
            they are already aware.
        
      
        """
        pass
  
    @dbus.service.signal('org.freedesktop.Telepathy.Connection.Interface.Requests', signature='o')
    def ChannelClosed(self, Removed):
        """
        Emitted when a channel is closed and hence disappears from the
        Channels property.

        
          This is redundant with the Closed
          signal on the channel itself, but it does provide full change
          notification for the Channels property.
        
      
        """
        pass class ConnectionInterfaceMailNotification(dbus.service.Interface):
    """\
      An interface to support receiving notifications about a e-mail
        account associated with this connection.

      In protocols where this is possible, this interface also allows the
        connection manager to provide the necessary information for clients
        to open a web-based mail client without having to re-authenticate.

      To use this interface, a client MUST first subscribe by passing the
        name of this interface to the Connection.AddClientInterest method. The subscription
        mechanic aims at reducing network traffic and memory footprint in the
        situation where nobody is currently interesting in provided
        information. When done with this interface, clients SHOULD call
        Connection.RemoveClientInterest to allow the CM to
        release resources.

      Protocols have various different levels of Mail Notification support.
        To describe the level of support, the interface provides a property
        called MailNotificationFlags.
        Not all combinations are valid; protocols can be divided into four
        categories as follows.

      Connections to the most capable protocols, such as Google's XMPP Mail
        Notification extension, have the Supports_Unread_Mails flag (this
        implies that they must also have Supports_Unread_Mail_Count, but not
        Emits_Mails_Received). On these connections, clients
        requiring change notification MUST monitor the
        UnreadMailsChanged signal, and
        either recover the initial state from the
        UnreadMails property (if they require
        details other than the number of mails) or the
        UnreadMailCount property (if they
        are only interested in the number of unread mails). The
        MailsReceived signal is never emitted
        on these connections, so clients that will display a short-term
        notification for each new mail MUST do so in response to emission of
        the UnreadMailsChanged signal.

      The most common situation, seen in protocols like MSN and Yahoo, is
        that the number of unread mails is provided and kept up-to-date,
        and a separate notification is emitted with some details of each new
        mail. This is a combination of the following two features, and clients
        SHOULD implement one or both as appropriate for their requirements.

      On protocols that have the Emits_Mails_Received flag (which implies
        that they do not have Supports_Unread_Mails), the CM does not keep
        track of any mails; it simply emits a notification whenever new mail
        arrives. Those events may be used for short term display (like a
        notification popup) to inform the user. No protocol is known to support
        only this feature, but it is useful for integration with libraries that
        that do not implement tracking of the number of mails. Clients
        requiring these notifications MUST monitor the
        MailsReceived signal on any connections
        with this flag.

      On protocols that have the Supports_Unread_Mail_Count flag but not
        the Supports_Unread_Mails flag, clients cannot display complete
        details of unread email, but can display an up-to-date count of the
        number of unread mails. To do this, they must monitor the
        UnreadMailsChanged signal, and
        retrieve the initial state from the
        UnreadMailCount property.

      
        Orthogonal features described by the
        MailNotificationFlags property include the
        RequestSomethingURL methods, which are used to obtain URLs allowing
        clients to open a webmail client. Connections SHOULD support as many
        of these methods as possible.
    """

    def __init__(self):
        self._interfaces.add('org.freedesktop.Telepathy.Connection.Interface.MailNotification')

    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.MailNotification', in_signature='', out_signature='(sua(ss))')
    def RequestInboxURL(self):
        """
        This method creates and returns a URL and an optional POST data that
        allow opening the Inbox folder of a webmail account. This URL MAY
        contain tokens with a short lifetime, so clients SHOULD request a new
        URL for each visit to the webmail interface. This method is implemented
        only if the Supports_Request_Inbox_URL flag is set in
        MailNotificationFlags.

        
          We are not using properties here because the tokens are unsuitable
          for sharing between clients, and network round-trips may be required
          to obtain the information that leads to authentication free webmail
          access.
        
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.MailNotification', in_signature='sv', out_signature='(sua(ss))')
    def RequestMailURL(self, ID, URL_Data):
        """
        This method creates and returns a URL and optional POST data that
        allow opening a specific mail in a webmail interface. This
        method is implemented only if Supports_Request_Mail_URL flag
        is set in MailNotificationFlags.
        
          See RequestInboxURL for design
          rationale.
        
      
        """
        raise NotImplementedError
  
    @dbus.service.signal('org.freedesktop.Telepathy.Connection.Interface.MailNotification', signature='aa{sv}')
    def MailsReceived(self, Mails):
        """
        Emitted when new e-mails messages arrive to the inbox associated with
        this connection. This signal is used for protocols that are not able
        to maintain the UnreadMails list, but
        do provide real-time notification about newly arrived e-mails. It MUST
        NOT be emitted unless Emits_Mails_Received is set in
        MailNotificationFlags.
      
        """
        pass
  
    @dbus.service.signal('org.freedesktop.Telepathy.Connection.Interface.MailNotification', signature='uaa{sv}as')
    def UnreadMailsChanged(self, Count, Mails_Added, Mails_Removed):
        """
        Emitted when UnreadMails or
          UnreadMailCount have changed. It MUST
          NOT be emited if Supports_Unread_Mail_Count flag is not set
          in MailNotificationFlags.

        Mails_Added and
          Mails_Removed MUST be empty if the
          Supports_Unread_Mails flag is not set.
      
        """
        pass class ConnectionInterfacePresence(dbus.service.Interface):
    """\

      This interface is for services which have a concept of presence which
        can be published for yourself and monitored on your contacts.
        Telepathy's definition of presence is based on that used by
        the Galago project.

    Presence on an individual (yourself or one of your contacts) is modelled as
    a last activity time along with a set of zero or more statuses, each of
    which may have arbitrary key/value parameters. Valid statuses are defined
    per connection, and a list of them can be obtained with the
    GetStatuses method.

    (The SimplePresence interface which replaces this one restricts
      presences to one status per contact, with an optional message, which is
      in practice all that was implemented on this interface.)

    Each status has an arbitrary string identifier which should have an agreed
    meaning between the connection manager and any client which is expected to
    make use of it. The well-known values defined by the SimplePresence
      interface SHOULD be used where possible

    As well as these well-known status identifiers, every status also has a
    numerical type value chosen from
    Connection_Presence_Type which can be used by the client
    to classify even unknown statuses into different fundamental types.

    These numerical types exist so that even if a client does not understand
    the string identifier being used, and hence cannot present the presence to
    the user to set on themselves, it may display an approximation of the
    presence if it is set on a contact.

    The dictionary of variant types allows the connection manager to exchange
    further protocol-specific information with the client. It is recommended
    that the string (s) argument 'message' be interpreted as an optional
    message which can be associated with a presence status.

    If the connection has a 'subscribe' contact list,
    PresenceUpdate signals should be emitted to
    indicate changes of contacts on this list, and should also be emitted for
    changes in your own presence. Depending on the protocol, the signal may
    also be emitted for others such as people with whom you are communicating,
    and any user interface should be updated accordingly.

    On some protocols, RequestPresence may
    only succeed on contacts on your 'subscribe' list, and other contacts will
    cause a PermissionDenied error.  On protocols where there is no 'subscribe'
    list, and RequestPresence succeeds, a client may poll the server
    intermittently to update any display of presence information.
    """

    def __init__(self):
        self._interfaces.add('org.freedesktop.Telepathy.Connection.Interface.Presence')

    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Presence', in_signature='sa{sv}', out_signature='')
    def AddStatus(self, Status, Parameters):
        """
        Request that a single presence status is published for the user, along
        with any desired parameters. Changes will be indicated by
        PresenceUpdate signals being emitted.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Presence', in_signature='', out_signature='')
    def ClearStatus(self):
        """
        Request that all of a user's presence statuses be removed. Be aware
        that this request may simply result in the statuses being replaced by a
        default available status. Changes will be indicated by
        PresenceUpdate signals being emitted.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Presence', in_signature='au', out_signature='a{u(ua{sa{sv}})}')
    def GetPresence(self, Contacts):
        """
        Get presence previously emitted by
        PresenceUpdate for the given contacts.
        Data is returned in the same structure as the PresenceUpdate signal.
        Using this method in favour of
        RequestPresence has the advantage that
        it will not wake up each client connected to the PresenceUpdate signal.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Presence', in_signature='', out_signature='a{s(ubba{ss})}')
    def GetStatuses(self):
        """
        Get a dictionary of the valid presence statuses for this connection.
        This is only available when online because only some statuses will
        be available on some servers.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Presence', in_signature='s', out_signature='')
    def RemoveStatus(self, Status):
        """
        Request that the given presence status is no longer published for the
        user. Changes will be indicated by
        PresenceUpdate signals being emitted. As
        with ClearStatus, removing a status may
        actually result in it being replaced by a default available status.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Presence', in_signature='au', out_signature='')
    def RequestPresence(self, Contacts):
        """
        Request the presence for contacts on this connection. A PresenceUpdate
        signal will be emitted when they are received. This is not the same as
        subscribing to the presence of a contact, which must be done using the
        'subscription' ContactList,
        and on some protocols presence information may not be available unless
        a subscription exists.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Presence', in_signature='u', out_signature='')
    def SetLastActivityTime(self, Time):
        """
        Request that the recorded last activity time for the user be updated on
        the server.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Presence', in_signature='a{sa{sv}}', out_signature='')
    def SetStatus(self, Statuses):
        """
        Request that the user's presence be changed to the given statuses
          and desired parameters. Changes will be reflected by
          PresenceUpdate
          signals being emitted.

        Statuses whose Connection_Presence_Type
          is Offline, Error or Unknown MUST NOT be passed to this
          function. Connection managers SHOULD reject these statuses.

        
          The same rationale as for SimplePresence.SetPresence
            applies.
        

        On certain protocols, this method may be
          called on a newly-created connection which is still in the
          DISCONNECTED state, and will sign on with the requested status.
          If the requested status is not available after signing on,
          NotAvailable will be returned and the connection will remain
          offline, or if the protocol does not support signing on with
          a certain status, Disconnected will be returned.
      
        """
        raise NotImplementedError
  
    @dbus.service.signal('org.freedesktop.Telepathy.Connection.Interface.Presence', signature='a{u(ua{sa{sv}})}')
    def PresenceUpdate(self, Presence):
        """
        This signal should be emitted when your own presence has been changed,
        or the presence of the member of any of the connection's channels has
        been changed, or when the presence requested by
        RequestPresence is available.
      
        """
        pass class ConnectionInterfaceSimplePresence(dbus.service.Interface):
    """\
      This interface is for services which have a concept of presence which
        can be published for yourself and monitored on your contacts.

      Presence on an individual (yourself or one of your contacts) is
        modelled as a status and a status message. Valid statuses are defined
        per connection, and a list of those that can be set on youself
        can be obtained from the
        Statuses
        property.

      Each status has an arbitrary string identifier which should have an
        agreed meaning between the connection manager and any client which is
        expected to make use of it. The following well-known values should be
        used where possible to allow clients to identify common choices:

      
        
          status identifier
          Connection_Presence_Type
          comments
        
        
          available
          Connection_Presence_Type_Available
          
        
        
          away
          Connection_Presence_Type_Away
          
        
        
          brb
          Connection_Presence_Type_Away
          Be Right Back (a more specific form of Away)
        
        
          busy
          Connection_Presence_Type_Busy
          
        
        dnd
          Connection_Presence_Type_Busy
          Do Not Disturb (a more specific form of Busy)
        
        
          xa
          Connection_Presence_Type_Extended_Away
          Extended Away
        
        
          hidden
          Connection_Presence_Type_Hidden
          Also known as "Invisible" or "Appear Offline"
        
        
          offline
          Connection_Presence_Type_Offline
          
        
        
          unknown
          Connection_Presence_Type_Unknown
          special, see below
        
        
          error
          Connection_Presence_Type_Error
          special, see below
        
      

      As well as these well-known status identifiers, every status also has
        a numerical type value chosen from
        Connection_Presence_Type which can be
        used by the client to classify even unknown statuses into different
        fundamental types.

      These numerical types exist so that even if a client does not
        understand the string identifier being used, and hence cannot present
        the presence to the user to set on themselves, it may display an
        approximation of the presence if it is set on a contact.

      As well as the normal status identifiers, there are two special ones
        that may be present: 'unknown' with type Unknown and 'error' with type
        Error. 'unknown' indicates that it is impossible to determine the
        presence of a contact at this time, for example because it's not on the
        'subscribe' list and the protocol only allows one to determine the
        presence of contacts you're subscribed to. 'error' indicates that there
        was a failure in determining the status of a contact.

      If the connection has a 'subscribe' contact list,
        PresencesChanged
        signals should be emitted to indicate changes of contacts on this list,
        and should also be emitted for changes in your own presence. Depending
        on the protocol, the signal may also be emitted for others such as
        people with whom you are communicating, and any user interface should
        be updated accordingly.
    """

    def __init__(self):
        self._interfaces.add('org.freedesktop.Telepathy.Connection.Interface.SimplePresence')

    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.SimplePresence', in_signature='ss', out_signature='')
    def SetPresence(self, Status, Status_Message):
        """
        Request that the presence status and status message are published for
          the connection.  Changes will be indicated by
          PresencesChanged
          signals being emitted.

        This method may be called on a newly-created connection while it
          is still in the DISCONNECTED state, to request that when the
          connection connects, it will do so with the selected status.

        In DISCONNECTED state the
          Statuses
          property will indicate which statuses are allowed to be set
          while DISCONNECTED (none, if the Connection Manager doesn't allow
          this). This value MUST NOT be cached, as the set of allowed
          presences might change upon connecting.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.SimplePresence', in_signature='au', out_signature='a{u(uss)}')
    def GetPresences(self, Contacts):
        """
        Get presence previously emitted by
        PresencesChanged for the given
        contacts. Data is returned in the same structure as the
        PresencesChanged signal; no additional network requests are made.
      
        """
        raise NotImplementedError
  
    @dbus.service.signal('org.freedesktop.Telepathy.Connection.Interface.SimplePresence', signature='a{u(uss)}')
    def PresencesChanged(self, Presence):
        """
        This signal should be emitted when your own presence has been changed,
        or the presence of the member of any of the connection's channels has
        been changed.
      
        """
        pass class ConnectionInterfaceContacts(dbus.service.Interface):
    """\
      This interface allows many attributes of many contacts to be
        obtained in a single D-Bus round trip.

      Each contact attribute has an string identifier
        (Contact_Attribute), which is namespaced
        by the D-Bus interface which defines it.
    """

    def __init__(self):
        self._interfaces.add('org.freedesktop.Telepathy.Connection.Interface.Contacts')

    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Contacts', in_signature='auasb', out_signature='a{ua{sv}}')
    def GetContactAttributes(self, Handles, Interfaces, Hold):
        """
        Return any number of contact attributes for the given handles.
      
        """
        raise NotImplementedError class ConnectionInterfaceContactList(dbus.service.Interface):
    """\
      An interface for connections that have any concept of a list of
        known contacts (roster, buddy list, friends list etc.)

      
        On many protocols, there's a server-side roster (as in XMPP),
          or a set of server-side lists that can be combined to form a
          roster (as in MSN).

        In some protocols (like link-local XMPP), while there might not be
          any server or roster, it's possible to list "nearby" contacts.

        In Telepathy 0.20 and older, we represented contact lists as a
          collection of ContactList channels. This is remarkably difficult to
          work with in practice - every client that cares about contact lists
          has to take the union of some hard-to-define set of these
          channels - and conflicts with the idea that channels that cannot
          be dispatched to a handler should be closed.
      

      The list of contacts is not exposed as a D-Bus property; it can be
        fetched using GetContactListAttributes.
      

      
        In some protocols, such as XMPP, the contact list may not be
          available immediately. The
          GetContactListAttributes method
          will fail until the contact list is available.
          Using a method also allows extra attributes to be retrieved at
          the same time.
      
    """

    def __init__(self):
        self._interfaces.add('org.freedesktop.Telepathy.Connection.Interface.ContactList')

    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.ContactList', in_signature='asb', out_signature='a{ua{sv}}')
    def GetContactListAttributes(self, Interfaces, Hold):
        """
        Return some contact attributes for a list of contacts
          associated with the user. This list MUST include at least:

        
          all contacts whose subscribe
            attribute is not No
          all contacts whose publish
            attribute is not No
        

        but MAY contain other contacts.

        
          For instance, on XMPP, all contacts on the roster would appear
            here even if they have subscription="none", unless there's
            reason to believe the user does not want to see them (such as
            having been blocked).
        

        This list does not need to contain every visible contact: for
          instance, contacts seen in XMPP or IRC chatrooms SHOULD NOT appear
          here. Blocked contacts SHOULD NOT appear here, unless they still
          have a non-No subscribe or
          publish attribute
          for some reason.

        
          It's reasonable to assume that blocked contacts should not be
            visible to the user unless they specifically go looking for them,
            at least in protocols like XMPP where blocking a contact
            suppresses presence.
        
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.ContactList', in_signature='aus', out_signature='')
    def RequestSubscription(self, Contacts, Message):
        """
        Request that the given contacts allow the local user to
          subscribe to their presence, i.e. that their subscribe attribute
          becomes Yes.

        Connection managers SHOULD NOT attempt to enforce a
          mutual-subscription policy (i.e. when this method is called, they
          should not automatically allow the contacts to see the local user's
          presence). User interfaces that require mutual subscription
          MAY call AuthorizePublication
          at the same time as this method.

        
          Whether to enforce mutual subscription is a matter of policy,
            so it is left to the user interface and/or the server.
        

        Before calling this method on a connection where GetAliasFlags returns the User_Set flag,
          user interfaces SHOULD obtain, from the user, an alias to
          identify the contact in future, and store it using SetAliases.

        The user MAY be
          prompted using the contact's current self-assigned nickname, or
          something derived from the contact's (presumably self-assigned)
          identifier, as a default, but these names chosen by the contact
          SHOULD NOT be used without user approval.

        
          This is a generalization of
            XEP-0165 "Best Practices to Discourage JID Mimicking")
            to protocols other than XMPP. A reasonable user interface for
            this, as used in many XMPP clients, is to have a text entry
            for the alias adjacent to the text entry for the identifier
            to add.
        

        For contacts with subscribe=Yes, this method has no effect.
          It MUST return successfully if all contacts are in this state.

        For contacts with subscribe=Ask, this method SHOULD send a new
          request, with the given message, if allowed by the underlying
          protocol.

        For contacts with subscribe=No or subscribe=Rejected, this method
          SHOULD request that the contact allows the local user to subscribe
          to their presence; in general, this will change their publish
          attribute to Ask (although it could change directly to Yes in some
          situations).

        Any state changes that immediately result from this request MUST
          be signalled via ContactsChanged
          before this method returns.

        
          This makes it easy for user interfaces to see what practical
            effect this method had.
        

        If the remote contact accepts the request, their subscribe
          attribute will later change from Ask to Yes.

        If the remote contact explicitly rejects the request (in protocols
          that allow this), their subscribe attribute will later change from
          Ask to Rejected.

        If the subscription request is cancelled by the local user, the
          contact's subscribe attribute will change from Ask to No.

        This method SHOULD NOT be called until the
          ContactListState changes to Success.
          If the ContactListState changes to
          Failure, this method SHOULD raise the same error as
          GetContactListAttributes.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.ContactList', in_signature='au', out_signature='')
    def AuthorizePublication(self, Contacts):
        """
        For each of the given contacts, request that the local user's
          presence is sent to that contact, i.e. that their publish attribute
          becomes Yes.

        Connection managers SHOULD NOT attempt to enforce a
          mutual-subscription policy (i.e. when this method is called, they
          should not automatically request that the contacts allow the user to
          subscribe to their presence). User interfaces that require mutual
          subscription MAY call
          RequestSubscription at the same time
          as this method.

        
          Whether to enforce mutual subscription is a matter of policy,
            so it is left to the user interface and/or the server.
        

        For contacts with publish=Yes, this method has no effect; it
          MUST return successfully if all contacts given have this state.

        For contacts with publish=Ask, this method accepts the
          contact's request to see the local user's presence, changing
          their publish attribute from Ask to Yes.

        For contacts with publish=No, if the protocol allows it, this
          method allows the contacts to see the local user's presence even
          though they have not requested it, changing their publish attribute
          from No to Yes. Otherwise, it merely records the fact that
          presence publication to those contacts is allowed; if any of
          those contacts ask to receive the local user's presence
          later in the lifetime of the connection, the connection SHOULD
          immediately allow them to do so, changing their publish
          attribute directly from No to Yes.

        
          This makes it easy to implement the common UI policy that if
            the user attempts to subscribe to a contact's presence, requests
            for reciprocal subscription are automatically approved.
        

        Any state changes that immediately result from this request MUST
          be signalled via ContactsChanged
          before this method returns.

        
          This makes it easy for user interfaces to see what practical
            effect this method had.
        

        This method SHOULD NOT be called until the
          ContactListState changes to Success.
          If the ContactListState changes to
          Failure, this method SHOULD raise the same error as
          GetContactListAttributes.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.ContactList', in_signature='au', out_signature='')
    def RemoveContacts(self, Contacts):
        """
        Remove the given contacts from the contact list entirely. It is
          protocol-dependent whether this works, and under which
          circumstances.

        If possible, this method SHOULD set the contacts' subscribe and
          publish attributes to No, remove any stored aliases for those
          contacts, and remove the contacts from the result of
          GetContactListAttributes.

        This method SHOULD succeed even if it was not possible to carry out
          the request entirely or for all contacts (for instance, if there is an
          outstanding request to subscribe to the contact's presence, and it's
          not possible to cancel such requests). However, all signals that
          immediately result from this method call MUST be emitted before it
          returns, so that clients can interpret the result.

        
          User interfaces removing a contact from the contact list are
            unlikely to want spurious failure notifications resulting from
            limitations of a particular protocol. However, emitting the
            signals first means that if a client does want to check exactly
            what happened, it can wait for the method to return (while
            applying change-notification signals to its local cache of the
            contact list's state), then consult its local cache of the
            contact list's state to see whether the contact is still there.
        

        This method SHOULD NOT be called until the
          ContactListState changes to Success.
          If the ContactListState changes to
          Failure, this method SHOULD raise the same error as
          GetContactListAttributes.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.ContactList', in_signature='au', out_signature='')
    def Unsubscribe(self, Contacts):
        """
        Attempt to set the given contacts' subscribe attribute to No,
          i.e. stop receiving their presence.

        For contacts with subscribe=Ask, this attempts to cancel
          an earlier request to subscribe to the contact's presence; for
          contacts with subscribe=Yes, this attempts to
          unsubscribe from the contact's presence.

        As with RemoveContacts, this method
          SHOULD succeed even if it was not possible to carry out the request
          entirely or for all contacts; however, all signals that
          immediately result from this method call MUST be emitted before it
          returns.

        This method SHOULD NOT be called until the
          ContactListState changes to Success.
          If the ContactListState changes to
          Failure, this method SHOULD raise the same error as
          GetContactListAttributes.
      
        """
        raise NotImplementedError
  
    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.ContactList', in_signature='au', out_signature='')
    def Unpublish(self, Contacts):
        """
        Attempt to set the given contacts' publish attribute to No,
          i.e. stop sending presence to them.

        For contacts with publish=Ask, this method explicitly rejects the
          contact's request to subscribe to the user's presence; for
          contacts with publish=Yes, this method attempts to prevent the
          user's presence from being received by the contact.

        As with RemoveContacts, this method
          SHOULD succeed even if it was not possible to carry out the request
          entirely or for all contacts; however, all signals that
          immediately result from this method call MUST be emitted before it
          returns.

        This method SHOULD NOT be called until the
          ContactListState changes to Success.
          If the ContactListState changes to
          Failure, this method SHOULD raise the same error as
          GetContactListAttributes.
      
        """
        raise NotImplementedError
  
    @dbus.service.signal('org.freedesktop.Telepathy.Connection.Interface.ContactList', signature='u')
    def ContactListStateChanged(self, Contact_List_State):
        """
        Emitted when ContactListState
        changes.
      
        """
        pass
  
    @dbus.service.signal('org.freedesktop.Telepathy.Connection.Interface.ContactList', signature='a{u(uus)}au')
    def ContactsChanged(self, Changes, Removals):
        """
        Emitted when the contact list becomes available, when contacts'
          basic stored properties change, when new contacts are added to the
          list that would be returned by
          GetContactListAttributes,
          or when contacts are removed from that list.

        
          This provides change notification for that list, and for
            contacts' subscribe,
            publish and
            publish-request attributes.
        

        Connection managers SHOULD also emit this signal when a contact
          requests that the user's presence is published to them, even if
          that contact's publish attribute is already
          Ask and the publish-request has not changed.

        
          If the same contact sends 10 identical requests, 10 identical
            signals should be emitted.
        
      
        """
        pass
import dbus
import dbus.service
import re
import weakref
            import warnings
from telepathy.constants import (CONNECTION_STATUS_DISCONNECTED,
                                 CONNECTION_STATUS_CONNECTED,
                                 HANDLE_TYPE_NONE,
                                 HANDLE_TYPE_CONTACT,
                                 LAST_HANDLE_TYPE)
from telepathy.errors import (Disconnected, InvalidArgument,
                              InvalidHandle, NotAvailable,
                              NotImplemented)
from telepathy.interfaces import (CONN_INTERFACE,
                                  CONN_INTERFACE_ALIASING,
                                  CONN_INTERFACE_AVATARS,
                                  CONN_INTERFACE_CAPABILITIES,
                                  CONN_INTERFACE_PRESENCE,
                                  CONN_INTERFACE_RENAMING,
                                  CONNECTION_INTERFACE_MAIL_NOTIFICATION,
                                  CONNECTION_INTERFACE_REQUESTS,
                                  CHANNEL_INTERFACE)
from telepathy.server.handle import Handle, NoneHandle
from telepathy.server.properties import DBusProperties
from telepathy._generated.Connection import Connection as _Connection
from telepathy._generated.Connection_Interface_Aliasing \
        import ConnectionInterfaceAliasing
from telepathy._generated.Connection_Interface_Avatars \
        import ConnectionInterfaceAvatars
from telepathy._generated.Connection_Interface_Capabilities \
        import ConnectionInterfaceCapabilities \
        as _ConnectionInterfaceCapabilities
from telepathy._generated.Connection_Interface_Contact_Capabilities \
        import ConnectionInterfaceContactCapabilities \
        as _ConnectionInterfaceContactCapabilities
from telepathy._generated.Connection_Interface_Requests \
        import ConnectionInterfaceRequests \
        as _ConnectionInterfaceRequests
from telepathy._generated.Connection_Interface_Mail_Notification \
        import ConnectionInterfaceMailNotification
from telepathy._generated.Connection_Interface_Presence \
        import ConnectionInterfacePresence
from telepathy._generated.Connection_Interface_Simple_Presence \
        import ConnectionInterfaceSimplePresence
from telepathy._generated.Connection_Interface_Contacts \
        import ConnectionInterfaceContacts
from telepathy._generated.Connection_Interface_Contact_List \
        import ConnectionInterfaceContactList
            if spec_old != spec_new or gen_old != gen_new:
                caps.append((self._self_handle, ctype, gen_old, gen_new,
                            spec_old, spec_new))

        self.CapabilitiesChanged(caps)

        # return all my capabilities
        return [(ctype, caps[1]) for ctype, caps in my_caps.items()]

    def _diff_capabilities(self, handle, ctype, new_gen=None,
            new_spec=None, added_gen=None, added_spec=None):
        """Helper function to diff new caps with actual capabilities."""

        if handle in self._caps and ctype in self._caps[handle]:
            old_gen, old_spec = self._caps[handle][ctype]
        else:
            old_gen = 0
            old_spec = 0

        if new_gen is None:
            new_gen = old_gen
        if new_spec is None:
            new_spec = old_spec
        if added_gen:
            new_gen |= added_gen
        if added_spec:
            new_spec |= new_spec

        if old_gen != new_gen or old_spec != new_spec:
            diff = (int(handle), ctype, old_gen, new_gen, old_spec, new_spec)
            return diff

        return None


class ConnectionInterfaceContactCapabilities(_ConnectionInterfaceContactCapabilities):
    def __init__(self):
        _ConnectionInterfaceContactCapabilities.__init__(self)
        # { contact handle : list(Requestable Channel Class}
        # RCC signature is a(a{sv}as)
        self._contact_caps = {}

    def GetContactCapabilities(self, handles):
        if 0 in handles:
            raise InvalidHandle('Contact handle list contains zero')

        ret = dbus.Dictionary({}, signature='ua(a{sv}as)')
        for handle in handles:
            self.check_handle(HANDLE_TYPE_CONTACT, handle)
            caps = self._contact_caps.get(handle, [])
            ret[handle] = dbus.Array(caps, signature='(a{sv}as)')

        return ret


class ConnectionInterfaceRequests(
    _ConnectionInterfaceRequests,
    DBusProperties):

    def __init__(self):
        _ConnectionInterfaceRequests.__init__(self)
        DBusProperties.__init__(self)

        self._implement_property_get(CONNECTION_INTERFACE_REQUESTS,
            {'Channels': lambda: dbus.Array(self._get_channels(),
                signature='(oa{sv})'),
            'RequestableChannelClasses': lambda: dbus.Array(
                self._channel_manager.get_requestable_channel_classes(),
                signature='(a{sv}as)')})

    def _get_channels(self):
        return [(c._object_path, c.get_immutable_properties()) \
                for c in self._channels]

    def _check_basic_properties(self, props):
        # ChannelType must be present and must be a string.
        if CHANNEL_INTERFACE + '.ChannelType' not in props or \
                not isinstance(props[CHANNEL_INTERFACE + '.ChannelType'],
                    dbus.String):
            raise InvalidArgument('ChannelType is required')

        def check_valid_type_if_exists(prop, fun):
            p = CHANNEL_INTERFACE + '.' + prop
            if p in props and not fun(props[p]):
                raise InvalidArgument('Invalid %s' % prop)

        # Allow TargetHandleType to be missing, but not to be otherwise broken.
        check_valid_type_if_exists('TargetHandleType',
            lambda p: p >= 0 and p <= LAST_HANDLE_TYPE)

        # Allow TargetType to be missing, but not to be otherwise broken.
        check_valid_type_if_exists('TargetHandle',
            lambda p: p > 0 and p < (2**32)-1)
        if props.get(CHANNEL_INTERFACE + '.TargetHandle') == 0:
            raise InvalidArgument("TargetHandle may not be 0")

        # Allow TargetID to be missing, but not to be otherwise broken.
        check_valid_type_if_exists('TargetID',
            lambda p: isinstance(p, dbus.String))

        # Disallow InitiatorHandle, InitiatorID and Requested.
        check_valid_type_if_exists('InitiatorHandle', lambda p: False)
        check_valid_type_if_exists('InitiatorID', lambda p: False)
        check_valid_type_if_exists('Requested', lambda p: False)

        type = props[CHANNEL_INTERFACE + '.ChannelType']
        handle_type = props.get(CHANNEL_INTERFACE + '.TargetHandleType',
                HANDLE_TYPE_NONE)
        handle = props.get(CHANNEL_INTERFACE + '.TargetHandle', 0)

        return (type, handle_type, handle)

    def _validate_handle(self, props):
        target_handle_type = props.get(CHANNEL_INTERFACE + '.TargetHandleType',
            HANDLE_TYPE_NONE)
        target_handle = props.get(CHANNEL_INTERFACE + '.TargetHandle', None)
        target_id = props.get(CHANNEL_INTERFACE + '.TargetID', None)

        # Handle type 0 cannot have a handle.
        if target_handle_type == HANDLE_TYPE_NONE and target_handle not in (None, 0):

            raise InvalidArgument('When TargetHandleType is NONE, ' +