Portability	portable
Stability	unstable
Maintainer	info@jonkri.com
Safe Haskell	None

Network.Xmpp

Contents

Session management
JID
Stanzas
Threads
Miscellaneous

Description

The Extensible Messaging and Presence Protocol (XMPP) is an open technology for near-real-time communication, which powers a wide range of applications including instant messaging, presence, multi-party chat, voice and video calls, collaboration, lightweight middleware, content syndication, and generalized routing of XML data. XMPP provides a technology for the asynchronous, end-to-end exchange of structured data by means of direct, persistent XML streams among a distributed network of globally addressable, presence-aware clients and servers.

Pontarius is an XMPP client library, implementing the core capabilities of XMPP (RFC 6120): setup and teardown of XML streams, channel encryption, authentication, error handling, and communication primitives for messaging.

Note that we are not recommending anyone to use Pontarius XMPP at this time as it's still in an experimental stage and will have its API and data types modified frequently.

Synopsis

Session management

data Session Source

newSession :: IO Session Source

Initializes a new XMPP session.

withConnection :: XmppConMonad a -> Session -> IO (Either StreamError a)Source

Run an XmppConMonad action in isolation. Reader and writer workers will be temporarily stopped and resumed with the new session details once the action returns. The action will run in the calling thread. Any uncaught exceptions will be interpreted as connection failure.

connect :: HostName -> Text -> XmppConMonad (Either StreamError ())Source

Connect to host with given address.

simpleConnect Source

Arguments

:: HostName	Target host name
-> Text	User name (authcid)
-> Text	Password
-> Maybe Text	Desired resource (or Nothing to let the server decide)
-> XmppConMonad Jid

The quick and easy way to set up a connection to an XMPP server

This will * connect to the host * secure the connection with TLS * authenticate to the server using either SCRAM-SHA1 (preferred) or Digest-MD5 * bind a resource * return the full JID you have been assigned

Note that the server might assign a different resource even when we send a preference.

startTLS :: TLSParams -> XmppConMonad (Either XmppTLSError ())Source

simpleAuth Source

Arguments

:: Text	The username
-> Text	The password
-> Maybe Text	The desired resource or `Nothing` to let the server assign one
-> XmppConMonad (Either AuthError Jid)

Authenticate to the server with the given username and password and bind a resource.

Prefers SCRAM-SHA1 over DIGEST-MD5.

auth :: [SaslHandler] -> Maybe Text -> XmppConMonad (Either AuthError Jid)Source

Authenticate to the server using the first matching method and bind a resource.

closeConnection :: Session -> IO ()Source

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.

endSession :: Session -> IO ()Source

End the current Xmpp session.

setConnectionClosedHandler :: (StreamError -> Session -> IO ()) -> Session -> IO ()Source

Sets the handler to be executed when the server connection is closed.

JID

data Jid Source

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.

Constructors

Jid

Fields

localpart :: !(Maybe Text): 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).
domainpart :: !Text: 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).
resourcepart :: !(Maybe Text): 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).

Instances

Eq Jid
Read Jid
Show Jid
IsString Jid

isBare :: Jid -> Bool Source

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

isFull :: Jid -> Bool Source

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

Stanzas

The basic protocol data unit in XMPP is the XML stanza. The stanza is essentially a fragment of XML that is sent over a stream. Stanzas come in 3 flavors:

Message, for traditional push-style message passing between peers
Presence, for communicating status updates
IQ (info/query), for request-response semantics communication

All stanza types have the following attributes in common:

The id attribute is used by the originating entity to track any response or error stanza that it might receive in relation to the generated stanza from another entity (such as an intermediate server or the intended recipient). It is up to the originating entity whether the value of the id attribute is unique only within its current stream or unique globally.
The from attribute specifies the JID of the sender.
The to attribute specifies the JID of the intended recipient for the stanza.
The type attribute specifies the purpose or context of the message, presence, or IQ stanza. The particular allowable values for the 'type' attribute vary depending on whether the stanza is a message, presence, or IQ stanza.

getStanzaChan :: Session -> IO (TChan Stanza)Source

Get a duplicate of the stanza channel

Messages

The message stanza is a push mechanism whereby one entity pushes information to another entity, similar to the communications that occur in a system such as email.

http://xmpp.org/rfcs/rfc6120.html#stanzas-semantics-message

data Message Source

The message stanza. Used for push type communication.

Constructors

Message
Fields messageID :: !(Maybe StanzaId) messageFrom :: !(Maybe Jid) messageTo :: !(Maybe Jid) messageLangTag :: !(Maybe LangTag) messageType :: !MessageType messagePayload :: ![Element]

Instances

Show Message

data MessageError Source

An error stanza generated in response to a Message.

Constructors

MessageError
Fields messageErrorID :: !(Maybe StanzaId) messageErrorFrom :: !(Maybe Jid) messageErrorTo :: !(Maybe Jid) messageErrorLangTag :: !(Maybe LangTag) messageErrorStanzaError :: !StanzaError messageErrorPayload :: ![Element]

Instances

Show MessageError

data MessageType Source

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

Constructors

Chat	The message is sent in the context of a one-to-one chat session. Typically an interactive client will present a message of type chat in an interface that enables one-to-one chat between the two parties, including an appropriate conversation history.
GroupChat	The message is sent in the context of a multi-user chat environment (similar to that of `IRC`). Typically a receiving client will present a message of type groupchat in an interface that enables many-to-many chat between the parties, including a roster of parties in the chatroom and an appropriate conversation history.
Headline	The message provides an alert, a notification, or other transient information to which no reply is expected (e.g., news headlines, sports updates, near-real-time market data, or syndicated content). Because no reply to the message is expected, typically a receiving client will present a message of type headline in an interface that appropriately differentiates the message from standalone messages, chat messages, and groupchat messages (e.g., by not providing the recipient with the ability to reply).
Normal	The message is a standalone message that is sent outside the context of a one-to-one conversation or groupchat, and to which it is expected that the recipient will reply. Typically a receiving client will present a message of type normal in an interface that enables the recipient to reply, but without a conversation history. This is the default value.

Instances

Eq MessageType
Read MessageType
Show MessageType

Creating

answerMessage :: Message -> [Element] -> Maybe Message Source

Sending

sendMessage :: Message -> Session -> IO ()Source

Send a message stanza.

Receiving

pullMessage :: Session -> IO (Either MessageError Message)Source

Read an element from the inbound stanza channel, acquiring a copy of the channel as necessary.

waitForMessage :: (Message -> Bool) -> Session -> IO Message Source

Pulls a (non-error) message and returns it if the given predicate returns True.

waitForMessageError :: (MessageError -> Bool) -> Session -> IO MessageError Source

Pulls an error message and returns it if the given predicate returns True.

filterMessages :: (MessageError -> Bool) -> (Message -> Bool) -> Session -> IO (Either MessageError Message)Source

Pulls a message and returns it if the given predicate returns True.

Presence

XMPP includes the ability for an entity to advertise its network availability, or presence, to other entities. In XMPP, this availability for communication is signaled end-to-end by means of a dedicated communication primitive: the presence stanza.

data Presence Source

The presence stanza. Used for communicating status updates.

Constructors

Presence
Fields presenceID :: !(Maybe StanzaId) presenceFrom :: !(Maybe Jid) presenceTo :: !(Maybe Jid) presenceLangTag :: !(Maybe LangTag) presenceType :: !(Maybe PresenceType) presencePayload :: ![Element]

Instances

Show Presence

data PresenceError Source

An error stanza generated in response to a Presence.

Constructors

PresenceError
Fields presenceErrorID :: !(Maybe StanzaId) presenceErrorFrom :: !(Maybe Jid) presenceErrorTo :: !(Maybe Jid) presenceErrorLangTag :: !(Maybe LangTag) presenceErrorStanzaError :: !StanzaError presenceErrorPayload :: ![Element]

Instances

Show PresenceError

Creating

presTo :: Presence -> Jid -> Presence Source

Add a recipient to a presence notification.

Sending

Sends a presence stanza. In general, the presence stanza should have no to attribute, in which case the server to which the client is connected will broadcast that stanza to all subscribed entities. However, a publishing client may also send a presence stanza with a to attribute, in which case the server will route or deliver that stanza to the intended recipient.

sendPresence :: Presence -> Session -> IO ()Source

Send a presence stanza.

Receiving

pullPresence :: Session -> IO (Either PresenceError Presence)Source

Read an element from the inbound stanza channel, acquiring a copy of the channel as necessary.

waitForPresence :: (Presence -> Bool) -> Session -> IO Presence Source

Pulls a (non-error) presence and returns it if the given predicate returns True.

IQ

Info/Query, or IQ, is a request-response mechanism, similar in some ways to the Hypertext Transfer Protocol HTTP. The semantics of IQ enable an entity to make a request of, and receive a response from, another entity. The data content and precise semantics of the request and response is defined by the schema or other structural definition associated with the XML namespace that qualifies the direct child element of the IQ element. IQ interactions follow a common pattern of structured data exchange such as get/result or set/result (although an error can be returned in reply to a request if appropriate)

http://xmpp.org/rfcs/rfc6120.html#stanzas-semantics-iq

data IQRequest Source

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

Constructors

IQRequest
Fields iqRequestID :: !StanzaId iqRequestFrom :: !(Maybe Jid) iqRequestTo :: !(Maybe Jid) iqRequestLangTag :: !(Maybe LangTag) iqRequestType :: !IQRequestType iqRequestPayload :: !Element

Instances

Show IQRequest

data IQRequestTicket Source

Contains whether or not a reply has been sent, and the IQ request body to reply to.

iqRequestBody :: IQRequestTicket -> IQRequest Source

data IQRequestType Source

The type of IQ request that is made.

Constructors

Get
Set

Instances

Eq IQRequestType
Ord IQRequestType
Read IQRequestType
Show IQRequestType

data IQResult Source

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

Constructors

IQResult
Fields iqResultID :: !StanzaId iqResultFrom :: !(Maybe Jid) iqResultTo :: !(Maybe Jid) iqResultLangTag :: !(Maybe LangTag) iqResultPayload :: !(Maybe Element)

Instances

Show IQResult

data IQError Source

The answer to an IQ request that generated an error.

Constructors

IQError
Fields iqErrorID :: !StanzaId iqErrorFrom :: !(Maybe Jid) iqErrorTo :: !(Maybe Jid) iqErrorLangTag :: !(Maybe LangTag) iqErrorStanzaError :: !StanzaError iqErrorPayload :: !(Maybe Element)

Instances

Show IQError

data IQResponse Source

A response Info/Query (IQ) stanza is either an IQError, an IQ stanza of type result (IQResult) or a Timeout.

Constructors

IQResponseError IQError
IQResponseResult IQResult
IQResponseTimeout

Instances

Show IQResponse

sendIQ Source

Arguments

:: Maybe Int	Timeout
-> Maybe Jid	Recipient (to)
-> IQRequestType	IQ type (`Get` or `Set`)
-> Maybe LangTag	Language tag of the payload (`Nothing` for default)
-> Element	The IQ body (there has to be exactly one)
-> Session
-> IO (TMVar IQResponse)

Sends an IQ, returns a TMVar that will be filled with the first inbound IQ with a matching ID that has type result or error.

sendIQ' :: Maybe Jid -> IQRequestType -> Maybe LangTag -> Element -> Session -> IO IQResponse Source

Like sendIQ, but waits for the answer IQ. Times out after 3 seconds

answerIQ :: IQRequestTicket -> Either StanzaError (Maybe Element) -> Session -> IO Bool Source

listenIQChan Source

Arguments

:: IQRequestType	Type of IQs to receive (`Get` or `Set`)
-> Text	Namespace of the child element
-> Session
-> IO (Either (TChan IQRequestTicket) (TChan IQRequestTicket))

Retrieves an IQ listener channel. If the namespace/IQRequestType is not already handled, a new TChan is created and returned as a Right value. Otherwise, the already existing channel will be returned wrapped in a Left value. Note that the Left channel might need to be duplicated in order not to interfere with existing consumers.

Threads

forkSession :: Session -> IO Session Source

Create a forked session object

Miscellaneous

data LangTag Source

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).

Constructors

LangTag
Fields primaryTag :: !Text subtags :: ![Text]

Instances

Eq LangTag
Read LangTag
Show LangTag

exampleParams :: TLSParams Source