The Session object represents a single session with an XMPP server. You can use session to establish a session

Creates a Session object by setting up a connection with an XMPP server.

Will connect to the specified host with the provided configuration. If the third parameter is a Just value, session will attempt to authenticate and acquire an XMPP resource.

Changes the handler to be executed when the server connection is closed. To avoid race conditions the initial value should be set in the configuration when creating the session

Reconnect with the stored settings.

Waits a random amount of seconds (between 0 and 60 inclusive) before the first attempt and an increasing amount after each attempt after that. Caps out at 2-5 minutes.

This function does not set your presence to online, so you will have to do this yourself.

Reconnect with the stored settings with an unlimited number of retries.

Waits a random amount of seconds (between 0 and 60 inclusive) before the first attempt and an increasing amount after each attempt after that. Caps out at 2-5 minutes.

This function does not set your presence to online, so you will have to do this yourself.

Reconnect immediately with the stored settings. Returns Just the error when the reconnect attempt fails and Nothing when no failure was encountered.

This function does not set your presence to online, so you will have to do this yourself.

Configuration settings related to the stream.

Configuration for the Session object.

Specify the method with which the connection is (re-)established

Signals the state of the stream connection.

Close the connection to the server. Closes the stream (by enforcing a write lock and sending a </stream:stream> element), waits (blocks) for three seconds, and then closes the connection.

End the current XMPP session. Kills the associated threads and closes the connection.

Note that XMPP clients (that have signalled availability) should send "Unavailable" presence prior to disconnecting.

The connectionClosedHandler will not be called (to avoid possibly reestablishing the connection).

Wait until the connection of the stream is re-established

Tuple defining the SASL Handler's name, and a SASL mechanism computation. The SASL mechanism is a stateful Stream computation, which has the possibility of resulting in an authentication error.

SASL handlers and the desired JID resource

Nothing to disable authentication

The allowed SASL mecahnism can depend on the connection state. For example, plain should be avoided unless the connection state is Secured

It is recommended to leave the resource up to the server

Authenticate using, in order of preference, scramSha1, digestMd5 and finally, if both of those are not support and the stream is Secured with TLS, try plain

The resource will be decided by the server

A JID is XMPP's native format for addressing entities in the network. It is somewhat similar to an e-mail address but contains three parts instead of two: localpart, domainpart, and resourcepart.

The localpart of a JID is an optional identifier placed before the domainpart and separated from the latter by a '@' character. Typically a localpart uniquely identifies the entity requesting and using network access provided by a server (i.e., a local account), although it can also represent other kinds of entities (e.g., a chat room associated with a multi-user chat service). The entity represented by an XMPP localpart is addressed within the context of a specific domain (i.e., localpart@domainpart).

The domainpart typically identifies the home server to which clients connect for XML routing and data management functionality. However, it is not necessary for an XMPP domainpart to identify an entity that provides core XMPP server functionality (e.g., a domainpart can identify an entity such as a multi-user chat service, a publish-subscribe service, or a user directory).

The resourcepart of a JID is an optional identifier placed after the domainpart and separated from the latter by the '/' character. A resourcepart can modify either a localpart@domainpart address or a mere domainpart address. Typically a resourcepart uniquely identifies a specific connection (e.g., a device or location) or object (e.g., an occupant in a multi-user chat room) belonging to the entity associated with an XMPP localpart at a domain (i.e., localpart@domainpart/resourcepart).

For more details see RFC 6122 http://xmpp.org/rfcs/rfc6122.html

Constructs and validates a Jid at compile time.

Syntax: [jid|localpart@domainpart/resourcepart|]

>>> [jid|foo@bar/quux|]
parseJid "foo@bar/quux"

>>> Just [jid|foo@bar/quux|] == jidFromTexts (Just "foo") "bar" (Just "quux")
True

>>> Just [jid|foo@bar/quux|] == jidFromText "foo@bar/quux"
True

See also jidFromText

Synonym for jid

Returns True if the JID is bare, that is, it doesn't have a resource part, and False otherwise.

>>> isBare [jid|foo@bar|]
True

>>> isBare [jid|foo@bar/quux|]
False

Returns True if the JID is full, and False otherwise.

isFull = not . isBare

>>> isBare [jid|foo@bar|]
True

>>> isBare [jid|foo@bar/quux|]
False

Parse a JID

>>> localpart <$> jidFromText "foo@bar/quux"
Just (Just "foo")

>>> domainpart <$> jidFromText "foo@bar/quux"
Just "bar"

>>> resourcepart <$> jidFromText "foo@bar/quux"
Just (Just "quux")

• Counterexamples

A JID must only have one '@':

>>> jidFromText "foo@bar@quux"
Nothing

'@' must come before '/':

>>> jidFromText "foo/bar@quux"
Nothing

The domain part can't be empty:

>>> jidFromText "foo@/quux"
Nothing

Both the local part and the resource part can be omitted (but the '@' and '/', must also be removed):

>>> jidToTexts <$> jidFromText "bar"
Just (Nothing,"bar",Nothing)

>>> jidToTexts <$> jidFromText "@bar"
Nothing

>>> jidToTexts <$> jidFromText "bar/"
Nothing

Convert localpart, domainpart, and resourcepart to a JID. Runs the appropriate stringprep profiles and validates the parts.

>>> jidFromTexts (Just "foo") "bar" (Just "baz") == jidFromText "foo@bar/baz"
True

jidFromTexts (localpart j) (domainpart j) (resourcepart j) == Just j

Converts a JID to a Text.

Converts a JID to up to three Text values: (the optional) localpart, the domainpart, and (the optional) resourcepart.

>>> jidToTexts [jid|foo@bar/quux|]
(Just "foo","bar",Just "quux")

>>> jidToTexts [jid|bar/quux|]
(Nothing,"bar",Just "quux")

>>> jidToTexts [jid|foo@bar|]
(Just "foo","bar",Nothing)

jidToTexts j == (localpart j, domainpart j, resourcepart j)

Returns the Jid without the resourcepart (if any).

>>> toBare [jid|foo@bar/quux|] == [jid|foo@bar|]
True

Returns the localpart of the Jid (if any).

>>> localpart [jid|foo@bar/quux|]
Just "foo"

Returns the domainpart of the Jid.

>>> domainpart [jid|foo@bar/quux|]
"bar"

Returns the resourcepart of the Jid (if any).

>>> resourcepart [jid|foo@bar/quux|]
Just "quux"

Parses a JID string.

Note: This function is only meant to be used to reverse Jid Show operations; it will produce an undefined value if the JID does not validate; please refer to jidFromText for a safe equivalent.

Return the JID assigned to us by the server

Get the next incoming stanza

Get the channel of incoming stanzas.

Generates a new stanza identifier based on the sessionStanzaIDs field of SessionConfiguration.

The message stanza. Used for push type communication.

An empty message

message = Message { messageID      = Nothing
                  , messageFrom    = Nothing
                  , messageTo      = Nothing
                  , messageLangTag = Nothing
                  , messageType    = Normal
                  , messagePayload = []
                  }

An error stanza generated in response to a Message.

The type of a Message being sent (http://xmpp.org/rfcs/rfc6121.html#message-syntax-type)

Produce an answer message with the given payload, setting "from" to the "to" attributes in the original message. Produces a Nothing value of the provided message message has no "from" attribute. Sets the "from" attribute to Nothing to let the server assign one.

Send a message stanza. Returns False when the Message could not be sent.

Draw and discard stanzas from the inbound channel until a message or message error is found. Returns the message or message error.

Draw and discard stanzas from the inbound channel until a message is found. Returns the message.

Draw and discard stanzas from the inbound channel until a message is found. Returns the message with annotations.

Draw and discard stanzas from the inbound channel until a message matching the given predicate is found. Returns the matching message.

Draw and discard stanzas from the inbound channel until a message matching the given predicate is found. Returns the matching message with annotations.

Draw and discard stanzas from the inbound channel until a message error matching the given predicate is found. Returns the matching message error

Draw and discard stanzas from the inbound channel until a message error matching the given predicate is found. Returns the matching message error with annotations.

Draw and discard stanzas from the inbound channel until a message or message error matching the given respective predicate is found. Returns the matching message or message error.

Draw and discard stanzas from the inbound channel until a message or message error matching the given respective predicate is found. Returns the matching message or message error with annotations

The presence stanza. Used for communicating status updates.

PresenceType holds Xmpp presence types. The "error" message type is left out as errors are using PresenceError.

An error stanza generated in response to a Presence.

An empty presence.

Signal to the server that the client is no longer available for communication.

Signal to the server that the client is available for communication.

Request subscription with an entity.

Approve a subscripton of an entity.

End a subscription with an entity.

Deny a not-yet approved or terminate a previously approved subscription of an entity

Add a recipient to a presence notification.

Send a presence stanza.

Read a presence stanza from the inbound stanza channel, discards any other stanzas. Returns the presence stanza.

Draw and discard stanzas from the inbound channel until a presence stanza matching the given predicate is found. Return the presence stanza with annotations.

A "request" Info/Query (IQ) stanza is one with either "get" or "set" as type. It always contains an xml payload.

A received and wrapped up IQ request. Prevents you from (illegally) answering a single IQ request multiple times

The actual IQ request that created this ticket.

The type of IQ request that is made.

The (non-error) answer to an IQ request.

The answer to an IQ request that generated an error.

A "response" Info/Query (IQ) stanza is either an IQError, an IQ stanza of type "result" (IQResult)

Sends an IQ, returns an STM action that returns the first inbound IQ with a matching ID that has type result or error or Nothing if the timeout was reached.

When sending the action fails, an XmppFailure is returned.

Like sendIQ, but waits for the answer IQ. Discards plugin Annotations

Answer an IQ request. Only the first answer ist sent and Just True is returned when the answer is sucessfully sent. If an error occured during sending Just False is returned (and another attempt can be undertaken). Subsequent answers after the first sucessful one are dropped and (False is returned in that case)

Create an IQ Result matching an IQ request

Register your interest in inbound IQ stanzas of a specific type and namespace. The returned STM action yields the received, matching IQ stanzas.

If a handler for IQ stanzas with the given type and namespace is already registered, the producer will be wrapped in Left. In this case the returned request tickets may already be processed elsewhere.

Unregister a previously registered IQ handler. No more IQ stanzas will be delivered to any of the returned producers.

StanzaErrors always have one of these types.

All stanzas (IQ, message, presence) can cause errors, which in the Xmpp stream looks like <stanza-kind to='sender' type='error'> . These errors are wrapped in the StanzaError type. TODO: Sender XML is (optional and is) not yet included.

The RECOMMENDED error type associated with an error condition. The following conditions allow for multiple types

• FeatureNotImplemented: Cancel or Modify (returns Cancel)
• PolicyViolation: Modify or Wait (Modify)
• RemoteServerTimeout: Wait or unspecified other (Wait)
• UndefinedCondition: Any condition (Cancel)

Create a StanzaError with condition and the associatedErrorType. Leave the error text and the application specific condition empty

Stanza errors are accommodated with one of the error conditions listed below.

Error that can occur during sendIQ'

Duplicate the inbound channel of the session object. Most receiving functions discard stanzas they are not interested in from the inbound channel. Duplicating the channel ensures that those stanzas can aren't lost and can still be handled somewhere else.

Annotations are auxiliary data attached to received stanzas by Plugins to convey information regarding their operation. For example, a plugin for encryption might attach information about whether a received stanza was encrypted and which algorithm was used.

The language tag in accordance with RFC 5646 (in the form of "en-US"). It has a primary tag and a number of subtags. Two language tags are considered equal if and only if they contain the same tags (case-insensitive).

Parses, validates, and possibly constructs a LangTag object.

Signals an XMPP stream error or another unpredicted stream-related situation. This error is fatal, and closes the XMPP stream.

Encapsulates information about an XMPP stream error.

Signals a SASL authentication error condition.

Connect to an XMPP server and secure the connection with TLS before starting the XMPP streams

NB RFC 6120 does not specify this method, but some servers, notably GCS, seem to use it.

The default value for this type.