You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
247 lines
7.7 KiB
247 lines
7.7 KiB
-- | |
|
-- Module: $Header$ |
|
-- |
|
-- Maintainer: info@jonkri.com |
|
-- Stability: unstable |
|
-- Portability: portable |
|
-- |
|
-- 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 XMPP is an XMPP client library, implementing the core capabilities |
|
-- of XMPP (RFC 6120): setup and tear-down of XML streams, channel encryption, |
|
-- authentication, error handling, and communication primitives for messaging. |
|
-- |
|
-- For low-level access to Pontarius XMPP, see the "Network.Xmpp.Internal" |
|
-- module. |
|
-- |
|
-- Getting Started |
|
-- |
|
-- We use 'session' to create a session object and connect to a server. Here we |
|
-- use the default 'SessionConfiguration'. |
|
-- |
|
-- @ |
|
-- sess <- session realm (simpleAuth \"myUsername\" \"mypassword\") def |
|
-- @ |
|
-- |
|
-- Defining 'AuthData' can be a bit unwieldy, so 'simpleAuth' gives us a |
|
-- reasonable default. Though, for improved security, we should consider |
|
-- restricting the mechanisms to 'scramSha1' whenever we can. |
|
-- |
|
-- Next we have to set the presence to online, otherwise we won't be able to |
|
-- send or receive stanzas to/from other entities. |
|
-- |
|
-- @ |
|
-- sendPresence presenceOnline sess |
|
-- @ |
|
-- |
|
{-# LANGUAGE CPP, NoMonomorphismRestriction, OverloadedStrings #-} |
|
|
|
module Network.Xmpp |
|
( -- * Session management |
|
Session |
|
, session |
|
, setConnectionClosedHandler |
|
, reconnect |
|
, reconnect' |
|
, reconnectNow |
|
, StreamConfiguration(..) |
|
, SessionConfiguration(..) |
|
, ConnectionDetails(..) |
|
, ConnectionState(..) |
|
, closeConnection |
|
, endSession |
|
, waitForStream |
|
-- ** Authentication handlers |
|
-- | The use of 'scramSha1' is /recommended/, but 'digestMd5' might be |
|
-- useful for interaction with older implementations. |
|
, SaslHandler |
|
, AuthData |
|
, Username |
|
, Password |
|
, AuthZID |
|
, simpleAuth |
|
, scramSha1 |
|
, plain |
|
, digestMd5 |
|
-- * Addressing |
|
-- | A JID (historically: Jabber ID) is XMPPs native format |
|
-- for addressing entities in the network. It is somewhat similar to an e-mail |
|
-- address, but contains three parts instead of two. |
|
, Jid |
|
#if WITH_TEMPLATE_HASKELL |
|
, jid |
|
, jidQ |
|
#endif |
|
, isBare |
|
, isFull |
|
, jidFromText |
|
, jidFromTexts |
|
, jidToText |
|
, jidToTexts |
|
, toBare |
|
, localpart |
|
, domainpart |
|
, resourcepart |
|
, parseJid |
|
, getJid |
|
-- * 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 |
|
-- |
|
-- * /Info/\//Query/ (or /IQ/), 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. |
|
, getStanza |
|
, getStanzaChan |
|
, newStanzaID |
|
-- ** 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. It is not to be confused with |
|
-- an 'InstantMessage' |
|
, Message(..) |
|
, message |
|
, MessageError(..) |
|
, MessageType(..) |
|
-- *** Creating |
|
, answerMessage |
|
-- *** Sending |
|
, sendMessage |
|
-- *** Receiving |
|
, pullMessage |
|
, getMessage |
|
, getMessageA |
|
, waitForMessage |
|
, waitForMessageA |
|
, waitForMessageError |
|
, waitForMessageErrorA |
|
, filterMessages |
|
, filterMessagesA |
|
-- ** 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. |
|
, Presence(..) |
|
, PresenceType(..) |
|
, PresenceError(..) |
|
-- *** Creating |
|
, presence |
|
, presenceOffline |
|
, presenceOnline |
|
, presenceSubscribe |
|
, presenceSubscribed |
|
, presenceUnsubscribe |
|
, presenceUnsubscribed |
|
, presTo |
|
-- *** 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 |
|
-- *** Receiving |
|
, pullPresence |
|
, waitForPresence |
|
-- ** 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> |
|
, IQRequest(..) |
|
, IQRequestTicket |
|
, iqRequestBody |
|
, IQRequestType(..) |
|
, IQResult(..) |
|
, IQError(..) |
|
, IQResponse(..) |
|
, sendIQ |
|
, sendIQ' |
|
, answerIQ |
|
, iqResult |
|
, listenIQ |
|
, unlistenIQ |
|
-- * Errors |
|
, StanzaErrorType(..) |
|
, StanzaError(..) |
|
, associatedErrorType |
|
, mkStanzaError |
|
, StanzaErrorCondition(..) |
|
, SaslFailure(..) |
|
, IQSendError(..) |
|
-- * Threads |
|
, dupSession |
|
-- * Lenses |
|
-- | Network.Xmpp doesn't re-export the accessors to avoid name |
|
-- clashes. To use them import Network.Xmpp.Lens |
|
, module Network.Xmpp.Lens |
|
-- * Plugins |
|
-- Plugins modify incoming and outgoing stanzas. They can, for example, handle |
|
-- encryption, compression or other protocol extensions. |
|
, Annotated |
|
, Annotation(..) |
|
, Plugin |
|
, Plugin'(..) |
|
-- * LangTag |
|
, LangTag |
|
, langTagFromText |
|
, langTagToText |
|
, parseLangTag |
|
-- * Miscellaneous |
|
, XmppFailure(..) |
|
, StreamErrorInfo(..) |
|
, StreamErrorCondition(..) |
|
, AuthFailure( AuthNoAcceptableMechanism |
|
, AuthSaslFailure |
|
, AuthIllegalCredentials |
|
, AuthOtherFailure ) |
|
, connectTls |
|
, def |
|
) where |
|
|
|
import Network.Xmpp.Concurrent |
|
import Network.Xmpp.Sasl |
|
import Network.Xmpp.Sasl.Types |
|
import Network.Xmpp.Stanza |
|
import Network.Xmpp.Types |
|
import Network.Xmpp.Tls |
|
import Network.Xmpp.Lens hiding (view, set, modify) |
|
import Data.Default (def)
|
|
|