Client side XMPP roster protocol.

The roster can be retrieved using getRoster. Subsequent changes to the roster will be pushed, resulting in calls to setReceived or removeReceived. These methods should be overridden to handle the roster pushes.

RFC 6121 specifically allows entities other than a user's server to hold a roster for that user. However, how a client should deal with that is currently not yet specfied.

By default roster pushes from other source. I.e. when request.sender is set but the sender's bare JID is different from the user's bare JID. Set allowAnySender to allow roster pushes from any sender. To avert presence leaks, RosterPushIgnored should then be raised for pushes from untrusted senders.

If roster versioning is supported by the server, the roster and subsequent pushes are annotated with a version identifier. This can be used to cache the roster on the client side. Upon reconnect, the client can request the roster with the version identifier of the cached version. The server may then choose to only send roster pushes for the changes since that version, instead of a complete roster.

Class Variable allowAnySender Flag to allow roster pushes from any sender. False by default. (type: boolean)
Method connectionInitialized The XML stream has been initialized.
Method getRoster Retrieve contact list.
Method setItem Add or modify a roster item.
Method removeItem Remove an item from the contact list.
Method setReceived Called when a roster push for a new or update item was received.
Method removeReceived Called when a roster push for the removal of an item was received.
Method _onRosterSet Undocumented

Inherited from XMPPHandler:

Method __init__ Undocumented
Method setHandlerParent Set the parent of the handler.
Method disownHandlerParent Remove the parent of the handler.
Method makeConnection A connection over the underlying transport of the XML stream has been established.
Method connectionMade Called after a connection has been established.
Method connectionLost The XML stream has been closed.
Method send Send data over the managed XML stream.
Method request Send an IQ request and track the response.

Inherited from IQHandlerMixin:

Class Variable iqHandlers Mapping from XPath queries (as a string) to the method name that will handle requests that match the query. (type: dict)
Method handleRequest Find a handler and wrap the call for sending a response stanza.
allowAnySender =
Flag to allow roster pushes from any sender. False by default. (type: boolean)
def connectionInitialized(self): (source)

The XML stream has been initialized.

Can be overridden to perform work after stream initialization, e.g. to set up observers and start exchanging XML stanzas.

def getRoster(self, version=None): (source)

Retrieve contact list.

The returned deferred fires with the result of the roster request as Roster, a mapping from contact JID to RosterItem.

If roster versioning is supported, the recipient responds with either a the complete roster or with an empty result. In case of complete roster, the Roster is annotated with a version attribute that holds the version identifier for this version of the roster. This identifier should be used for caching.

If the recipient responds with an empty result, the returned deferred fires with None. This indicates that any roster modifications since version will be sent as roster pushes.

Note that the empty result (None) is different from an empty roster (Roster with no items).

ParametersversionOptional version identifier of the last cashed version of the roster. This shall only be set if the recipient is known to support roster versioning. If there is no (valid) cached version of the roster, but roster versioning is desired, version should be set to the empty string (u''). (type: unicode)
ReturnsRoster as a mapping from JID to RosterItem. (type: twisted.internet.defer.Deferred)
def setItem(self, item): (source)

Add or modify a roster item.

Note that RFC 6121 doesn't allow all properties of a roster item to be sent when setting a roster item. Only the name and groups attributes from item are sent to the server. Presence subscription management must be done through PresenceProtocol.

ParametersitemThe roster item to be set. (type: RosterItem.)
Returns (type: twisted.internet.defer.Deferred)
def removeItem(self, entity): (source)

Remove an item from the contact list.

ParametersentityThe contact to remove the roster item for. (type: JID)
Returns (type: twisted.internet.defer.Deferred)
def _onRosterSet(self, iq): (source)
Undocumented
def setReceived(self, request): (source)

Called when a roster push for a new or update item was received.

ParametersrequestThe push request. (type: RosterRequest)
def removeReceived(self, request): (source)

Called when a roster push for the removal of an item was received.

ParametersrequestThe push request. (type: RosterRequest)
API Documentation for wokkel, generated by pydoctor at 2018-12-06 14:45:46.