Portability | portable |
---|---|
Stability | unstable |
Maintainer | info@jonkri.com |
Safe Haskell | None |
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 teardown 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.
- data Session
- session :: HostName -> Maybe (ConnectionState -> [SaslHandler], Maybe Text) -> SessionConfiguration -> IO (Either XmppFailure Session)
- setConnectionClosedHandler :: (XmppFailure -> Session -> IO ()) -> Session -> IO ()
- reconnect :: Integer -> Session -> IO (Bool, [XmppFailure])
- reconnect' :: Session -> IO Integer
- reconnectNow :: Session -> IO (Maybe XmppFailure)
- data StreamConfiguration = StreamConfiguration {
- preferredLang :: !(Maybe LangTag)
- toJid :: !(Maybe (Jid, Bool))
- connectionDetails :: ConnectionDetails
- resolvConf :: ResolvConf
- establishSession :: Bool
- tlsBehaviour :: TlsBehaviour
- tlsParams :: TLSParams
- data SessionConfiguration = SessionConfiguration {
- sessionStreamConfiguration :: StreamConfiguration
- onConnectionClosed :: Session -> XmppFailure -> IO ()
- sessionStanzaIDs :: IO (IO Text)
- extraStanzaHandlers :: [StanzaHandler]
- enableRoster :: Bool
- data ConnectionDetails
- closeConnection :: Session -> IO ()
- endSession :: Session -> IO ()
- waitForStream :: Session -> IO ()
- scramSha1 :: Text -> Maybe Text -> Text -> SaslHandler
- plain :: Text -> Maybe Text -> Text -> SaslHandler
- digestMd5 :: Text -> Maybe Text -> Text -> SaslHandler
- data Jid
- jidQ :: QuasiQuoter
- isBare :: Jid -> Bool
- isFull :: Jid -> Bool
- jidFromText :: Text -> Maybe Jid
- jidFromTexts :: Maybe Text -> Text -> Maybe Text -> Maybe Jid
- jidToText :: Jid -> Text
- jidToTexts :: Jid -> (Maybe Text, Text, Maybe Text)
- toBare :: Jid -> Jid
- localpart :: Jid -> Maybe Text
- domainpart :: Jid -> Text
- resourcepart :: Jid -> Maybe Text
- parseJid :: String -> Jid
- getJid :: Session -> IO (Maybe Jid)
- getStanza :: Session -> IO Stanza
- getStanzaChan :: Session -> TChan Stanza
- newStanzaID :: Session -> IO Text
- data Message = Message {
- messageID :: !(Maybe Text)
- messageFrom :: !(Maybe Jid)
- messageTo :: !(Maybe Jid)
- messageLangTag :: !(Maybe LangTag)
- messageType :: !MessageType
- messagePayload :: ![Element]
- message :: Message
- data MessageError = MessageError {
- messageErrorID :: !(Maybe Text)
- messageErrorFrom :: !(Maybe Jid)
- messageErrorTo :: !(Maybe Jid)
- messageErrorLangTag :: !(Maybe LangTag)
- messageErrorStanzaError :: !StanzaError
- messageErrorPayload :: ![Element]
- data MessageType
- answerMessage :: Message -> [Element] -> Maybe Message
- sendMessage :: Message -> Session -> IO Bool
- pullMessage :: Session -> IO (Either MessageError Message)
- getMessage :: Session -> IO Message
- waitForMessage :: (Message -> Bool) -> Session -> IO Message
- waitForMessageError :: (MessageError -> Bool) -> Session -> IO MessageError
- filterMessages :: (MessageError -> Bool) -> (Message -> Bool) -> Session -> IO (Either MessageError Message)
- data Presence = Presence {
- presenceID :: !(Maybe Text)
- presenceFrom :: !(Maybe Jid)
- presenceTo :: !(Maybe Jid)
- presenceLangTag :: !(Maybe LangTag)
- presenceType :: !PresenceType
- presencePayload :: ![Element]
- data PresenceType
- = Subscribe
- | Subscribed
- | Unsubscribe
- | Unsubscribed
- | Probe
- | Available
- | Unavailable
- data PresenceError = PresenceError {
- presenceErrorID :: !(Maybe Text)
- presenceErrorFrom :: !(Maybe Jid)
- presenceErrorTo :: !(Maybe Jid)
- presenceErrorLangTag :: !(Maybe LangTag)
- presenceErrorStanzaError :: !StanzaError
- presenceErrorPayload :: ![Element]
- presence :: Presence
- presenceOffline :: Presence
- presenceOnline :: Presence
- presenceSubscribe :: Jid -> Presence
- presenceSubscribed :: Jid -> Presence
- presenceUnsubscribe :: Jid -> Presence
- presTo :: Presence -> Jid -> Presence
- sendPresence :: Presence -> Session -> IO Bool
- pullPresence :: Session -> IO (Either PresenceError Presence)
- waitForPresence :: (Presence -> Bool) -> Session -> IO Presence
- data IQRequest = IQRequest {
- iqRequestID :: !Text
- iqRequestFrom :: !(Maybe Jid)
- iqRequestTo :: !(Maybe Jid)
- iqRequestLangTag :: !(Maybe LangTag)
- iqRequestType :: !IQRequestType
- iqRequestPayload :: !Element
- data IQRequestTicket
- iqRequestBody :: IQRequestTicket -> IQRequest
- data IQRequestType
- data IQResult = IQResult {
- iqResultID :: !Text
- iqResultFrom :: !(Maybe Jid)
- iqResultTo :: !(Maybe Jid)
- iqResultLangTag :: !(Maybe LangTag)
- iqResultPayload :: !(Maybe Element)
- data IQError = IQError {
- iqErrorID :: !Text
- iqErrorFrom :: !(Maybe Jid)
- iqErrorTo :: !(Maybe Jid)
- iqErrorLangTag :: !(Maybe LangTag)
- iqErrorStanzaError :: !StanzaError
- iqErrorPayload :: !(Maybe Element)
- data IQResponse
- sendIQ :: Maybe Int -> Maybe Jid -> IQRequestType -> Maybe LangTag -> Element -> Session -> IO (Maybe (TMVar IQResponse))
- sendIQ' :: Maybe Jid -> IQRequestType -> Maybe LangTag -> Element -> Session -> IO (Maybe IQResponse)
- answerIQ :: IQRequestTicket -> Either StanzaError (Maybe Element) -> IO (Maybe Bool)
- listenIQChan :: IQRequestType -> Text -> Session -> IO (Either (TChan IQRequestTicket) (TChan IQRequestTicket))
- dropIQChan :: IQRequestType -> Text -> Session -> IO ()
- data StanzaError = StanzaError {}
- data StanzaErrorType
- data StanzaErrorCondition
- = BadRequest
- | Conflict
- | FeatureNotImplemented
- | Forbidden
- | Gone
- | InternalServerError
- | ItemNotFound
- | JidMalformed
- | NotAcceptable
- | NotAllowed
- | NotAuthorized
- | PaymentRequired
- | RecipientUnavailable
- | Redirect
- | RegistrationRequired
- | RemoteServerNotFound
- | RemoteServerTimeout
- | ResourceConstraint
- | ServiceUnavailable
- | SubscriptionRequired
- | UndefinedCondition
- | UnexpectedRequest
- data SaslFailure = SaslFailure {
- saslFailureCondition :: SaslError
- saslFailureText :: Maybe (Maybe LangTag, Text)
- dupSession :: Session -> IO Session
- data LangTag
- langTagFromText :: Text -> Maybe LangTag
- langTagToText :: LangTag -> Text
- parseLangTag :: String -> LangTag
- data XmppFailure
- = StreamErrorFailure StreamErrorInfo
- | StreamEndFailure
- | StreamCloseError ([Element], XmppFailure)
- | TcpConnectionFailure
- | XmppIllegalTcpDetails
- | TlsError TLSError
- | TlsNoServerSupport
- | XmppNoStream
- | XmppAuthFailure AuthFailure
- | TlsStreamSecured
- | XmppOtherFailure
- | XmppIOException IOException
- data StreamErrorInfo = StreamErrorInfo {
- errorCondition :: !StreamErrorCondition
- errorText :: !(Maybe (Maybe LangTag, Text))
- errorXml :: !(Maybe Element)
- data StreamErrorCondition
- = StreamBadFormat
- | StreamBadNamespacePrefix
- | StreamConflict
- | StreamConnectionTimeout
- | StreamHostGone
- | StreamHostUnknown
- | StreamImproperAddressing
- | StreamInternalServerError
- | StreamInvalidFrom
- | StreamInvalidNamespace
- | StreamInvalidXml
- | StreamNotAuthorized
- | StreamNotWellFormed
- | StreamPolicyViolation
- | StreamRemoteConnectionFailed
- | StreamReset
- | StreamResourceConstraint
- | StreamRestrictedXml
- | StreamSeeOtherHost
- | StreamSystemShutdown
- | StreamUndefinedCondition
- | StreamUnsupportedEncoding
- | StreamUnsupportedFeature
- | StreamUnsupportedStanzaType
- | StreamUnsupportedVersion
- data AuthFailure
- type SaslHandler = (Text, StateT StreamState IO (Either XmppFailure (Maybe AuthFailure)))
- data ConnectionState
- connectTls :: ResolvConf -> TLSParams -> String -> ErrorT XmppFailure IO StreamHandle
Session management
:: HostName | The hostname / realm |
-> Maybe (ConnectionState -> [SaslHandler], Maybe Text) | SASL handlers and the desired JID resource (or Nothing to let the server decide) |
-> SessionConfiguration | configuration details |
-> IO (Either XmppFailure Session) |
setConnectionClosedHandler :: (XmppFailure -> Session -> IO ()) -> Session -> IO ()Source
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
:: Integer | Maximum number of retries (numbers of 1 or less will perform exactly one retry) |
-> Session | Session to reconnect |
-> IO (Bool, [XmppFailure]) | Whether or not the reconnect attempt was successful, and a list of failure modes encountered |
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.
:: Session | Session to reconnect |
-> IO Integer | Number of failed retries before connection could be established |
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.
:: Session | session to reconnect |
-> IO (Maybe XmppFailure) |
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.
data StreamConfiguration Source
Configuration settings related to the stream.
StreamConfiguration | |
|
data SessionConfiguration Source
Configuration for the Session
object.
SessionConfiguration | |
|
data ConnectionDetails Source
UseRealm | Use realm to resolv host |
UseSrv HostName | Use this hostname for a SRV lookup |
UseHost HostName PortID | Use specified host |
UseConnection (ErrorT XmppFailure IO StreamHandle) |
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. Kills the associated threads and closes the connection.
Note that XMPP clients (that has signalled availability) should send "Unavailable" presence prior to disconnecting.
The connectionClosedHandler will not be called (to avoid possibly reestablishing the connection).
waitForStream :: Session -> IO ()Source
Wait until the connection of the stream is re-established
Authentication handlers
The use of scramSha1
is recommended, but digestMd5
might be
useful for interaction with older implementations.
:: Text | authentication ID (username) |
-> Maybe Text | authorization ID |
-> Text | password |
-> SaslHandler |
:: Text | Authentication identity (authcid or username) |
-> Maybe Text | Authorization identity (authzid) |
-> Text | Password |
-> SaslHandler |
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.
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
).
Constructs a Jid
value at compile time.
Syntax:
[jidQ|localpart@domainpart/resourcepart|]
jidFromText :: Text -> Maybe JidSource
Converts a Text to a JID.
jidFromTexts :: Maybe Text -> Text -> Maybe Text -> Maybe JidSource
Converts localpart, domainpart, and resourcepart strings to a JID. Runs the appropriate stringprep profiles and validates the parts.
jidToTexts :: Jid -> (Maybe Text, Text, Maybe Text)Source
Converts a JID to up to three Text values: (the optional) localpart, the domainpart, and (the optional) resourcepart.
domainpart :: Jid -> TextSource
Returns the domainpart of the Jid
.
resourcepart :: Jid -> Maybe TextSource
Returns the resourcepart of the Jid
(if any).
parseJid :: String -> JidSource
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.
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.
getStanzaChan :: Session -> TChan StanzaSource
Get the channel of incoming stanzas.
newStanzaID :: Session -> IO TextSource
Generates a new stanza identifier based on the sessionStanzaIDs
field of
SessionConfiguration
.
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
instant messaging which is handled in the IM
module
The message stanza. Used for push type communication.
Message | |
|
data MessageError Source
An error stanza generated in response to a Message
.
MessageError | |
|
data MessageType Source
The type of a Message being sent (http://xmpp.org/rfcs/rfc6121.html#message-syntax-type)
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 |
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. |
Creating
Sending
sendMessage :: Message -> Session -> IO BoolSource
Send a message stanza. Returns False
when the Message
could not be
sent.
Receiving
pullMessage :: Session -> IO (Either MessageError Message)Source
Read an element from the inbound stanza channel, discardes any non-Message stanzas from the channel
getMessage :: Session -> IO MessageSource
Get the next received message
waitForMessage :: (Message -> Bool) -> Session -> IO MessageSource
Pulls a (non-error) message and returns it if the given predicate returns
True
.
waitForMessageError :: (MessageError -> Bool) -> Session -> IO MessageErrorSource
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.
The presence stanza. Used for communicating status updates.
Presence | |
|
data PresenceType Source
PresenceType
holds Xmpp presence types. The error message type is left
out as errors are using PresenceError
.
Subscribe | Sender wants to subscribe to presence |
Subscribed | Sender has approved the subscription |
Unsubscribe | Sender is unsubscribing from presence |
Unsubscribed | Sender has denied or cancelled a subscription |
Probe | Sender requests current presence; should only be used by servers |
Available | Sender wants to express availability (no type attribute is defined) |
Unavailable |
data PresenceError Source
An error stanza generated in response to a Presence
.
PresenceError | |
|
Creating
presenceOffline :: PresenceSource
Signal to the server that the client is no longer available for communication.
presenceOnline :: PresenceSource
Signal to the server that the client is available for communication.
presenceSubscribe :: Jid -> PresenceSource
Request subscription with an entity.
presenceSubscribed :: Jid -> PresenceSource
Approve a subscripton of an entity.
presenceUnsubscribe :: Jid -> PresenceSource
End a subscription with an entity.
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.
Receiving
pullPresence :: Session -> IO (Either PresenceError Presence)Source
Read an element from the inbound stanza channel, discardes any non-Presence stanzas from the channel
waitForPresence :: (Presence -> Bool) -> Session -> IO PresenceSource
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)
A request Info/Query (IQ) stanza is one with either get or set as type. It always contains an xml payload.
IQRequest | |
|
data IQRequestTicket Source
Contains whether or not a reply has been sent, and the IQ request body to reply to.
data IQRequestType Source
The type of IQ request that is made.
The (non-error) answer to an IQ request.
IQResult | |
|
The answer to an IQ request that generated an error.
IQError | |
|
data IQResponse Source
:: Maybe Int | Timeout . When the timeout is reached the response
TMVar will be filled with |
-> Maybe Jid | Recipient (to) |
-> IQRequestType | IQ type ( |
-> Maybe LangTag | Language tag of the payload ( |
-> Element | The IQ body (there has to be exactly one) |
-> Session | |
-> IO (Maybe (TMVar IQResponse)) |
Sends an IQ, returns Just a TMVar
that will be filled with the first
inbound IQ with a matching ID that has type result
or error
or Nothing if
the stanza could not be sent
sendIQ' :: Maybe Jid -> IQRequestType -> Maybe LangTag -> Element -> Session -> IO (Maybe IQResponse)Source
Like sendIQ
, but waits for the answer IQ. Times out after 30 seconds
answerIQ :: IQRequestTicket -> Either StanzaError (Maybe Element) -> IO (Maybe Bool)Source
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)
:: IQRequestType | |
-> 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. The Left
channel might need to be duplicated in order not
to interfere with existing consumers.
Note thet every IQRequest
must be answered exactly once. To insure this,
the incoming requests are wrapped in an IQRequestTicket
that prevents
multiple responses. Use iqRequestBody
to extract the corresponding request
and answerIQ
to send the response
Unregister a previously acquired IQ channel. Please make sure that you where the one who acquired it in the first place as no check for ownership can be made
Errors
data StanzaError Source
All stanzas (IQ, message, presence) can cause errors, which in the Xmpp
stream looks like to='sender' type='error'. These errors are
wrapped in the StanzaError
type.
TODO: Sender XML is (optional and is) not yet included.
data StanzaErrorType Source
StanzaError
s always have one of these types.
data StanzaErrorCondition Source
Stanza errors are accommodated with one of the error conditions listed below.
BadRequest | Malformed XML. |
Conflict | Resource or session with name already exists. |
FeatureNotImplemented | |
Forbidden | Insufficient permissions. |
Gone | Entity can no longer be contacted at this address. |
InternalServerError | |
ItemNotFound | |
JidMalformed | |
NotAcceptable | Does not meet policy criteria. |
NotAllowed | No entity may perform this action. |
NotAuthorized | Must provide proper credentials. |
PaymentRequired | |
RecipientUnavailable | Temporarily unavailable. |
Redirect | Redirecting to other entity, usually temporarily. |
RegistrationRequired | |
RemoteServerNotFound | |
RemoteServerTimeout | |
ResourceConstraint | Entity lacks the necessary system resources. |
ServiceUnavailable | |
SubscriptionRequired | |
UndefinedCondition | Application-specific condition. |
UnexpectedRequest | Badly timed request. |
data SaslFailure Source
SaslFailure | |
|
Threads
dupSession :: Session -> IO SessionSource
Create a new session object with the inbound channel duplicated
Miscellaneous
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).
langTagFromText :: Text -> Maybe LangTagSource
Parses, validates, and possibly constructs a LangTag object.
langTagToText :: LangTag -> TextSource
parseLangTag :: String -> LangTagSource
data XmppFailure Source
Signals an XMPP stream error or another unpredicted stream-related situation. This error is fatal, and closes the XMPP stream.
StreamErrorFailure StreamErrorInfo | An error XML stream element has been encountered. |
StreamEndFailure | The stream has been closed.
This exception is caught by the
concurrent implementation, and
will thus not be visible
through use of |
StreamCloseError ([Element], XmppFailure) | When an XmppFailure is encountered in closeStreams, this constructor wraps the elements collected so far. |
TcpConnectionFailure | All attempts to TCP connect to the server failed. |
XmppIllegalTcpDetails | The TCP details provided did not validate. |
TlsError TLSError | An error occurred in the TLS layer |
TlsNoServerSupport | The server does not support the use of TLS |
XmppNoStream | An action that required an active
stream were performed when the
|
XmppAuthFailure AuthFailure | Authentication with the server failed (unrecoverably) |
TlsStreamSecured | Connection already secured |
XmppOtherFailure | Undefined condition. More information should be available in the log. |
XmppIOException IOException | An |
data StreamErrorInfo Source
Encapsulates information about an XMPP stream error.
StreamErrorInfo | |
|
data StreamErrorCondition Source
StreamBadFormat | The entity has sent XML that cannot be processed. |
StreamBadNamespacePrefix | The entity has sent a namespace prefix that is unsupported, or has sent no namespace prefix on an element that needs such a prefix |
StreamConflict | The server either (1) is closing the existing stream for this entity because a new stream has been initiated that conflicts with the existing stream, or (2) is refusing a new stream for this entity because allowing the new stream would conflict with an existing stream (e.g., because the server allows only a certain number of connections from the same IP address or allows only one server-to-server stream for a given domain pair as a way of helping to ensure in-order processing |
StreamConnectionTimeout | One party is closing the stream because it has reason to believe that the other party has permanently lost the ability to communicate over the stream. |
StreamHostGone | The value of the |
StreamHostUnknown | The value of the |
StreamImproperAddressing | A stanza sent between two servers lacks a
|
StreamInternalServerError | The server has experienced a misconfiguration or other internal error that prevents it from servicing the stream. |
StreamInvalidFrom | The data provided in a |
StreamInvalidNamespace | The stream namespace name is something other than "http:etherx.jabber.org/streams" (see Section 11.2) or the content namespace declared as the default namespace is not supported (e.g., something other than jabber:client or "jabber:server"). |
StreamInvalidXml | The entity has sent invalid XML over the stream to a server that performs validation |
StreamNotAuthorized | The entity has attempted to send XML stanzas or other outbound data before the stream has been authenticated, or otherwise is not authorized to perform an action related to stream negotiation; the receiving entity MUST NOT process the offending data before sending the stream error. |
StreamNotWellFormed | The initiating entity has sent XML that violates the well-formedness rules of [XML] or [XML‑NAMES]. |
StreamPolicyViolation | The entity has violated some local service policy (e.g., a stanza exceeds a configured size limit); the server MAY choose to specify the policy in the <text/> element or in an application-specific condition element. |
StreamRemoteConnectionFailed | The server is unable to properly connect to a remote entity that is needed for authentication or authorization (e.g., in certain scenarios related to Server Dialback [XEP‑0220]); this condition is not to be used when the cause of the error is within the administrative domain of the XMPP service provider, in which case the internal-server-error/ condition is more appropriate. |
StreamReset | The server is closing the stream because it has new (typically security-critical) features to offer, because the keys or certificates used to establish a secure context for the stream have expired or have been revoked during the life of the stream , because the TLS sequence number has wrapped, etc. The reset applies to the stream and to any security context established for that stream (e.g., via TLS and SASL), which means that encryption and authentication need to be negotiated again for the new stream (e.g., TLS session resumption cannot be used) |
StreamResourceConstraint | The server lacks the system resources necessary to service the stream. |
StreamRestrictedXml | he entity has attempted to send restricted XML features such as a comment, processing instruction, DTD subset, or XML entity reference |
StreamSeeOtherHost | The server will not provide service to the initiating entity but is redirecting traffic to another host under the administrative control of the same service provider. |
StreamSystemShutdown | The server is being shut down and all active streams are being closed. |
StreamUndefinedCondition | The error condition is not one of those defined by the other conditions in this list |
StreamUnsupportedEncoding | The initiating entity has encoded the stream in an encoding that is not supported by the server or has otherwise improperly encoded the stream (e.g., by violating the rules of the [UTF‑8] encoding). |
StreamUnsupportedFeature | The receiving entity has advertised a mandatory-to-negotiate stream feature that the initiating entity does not support, and has offered no other mandatory-to-negotiate feature alongside the unsupported feature. |
StreamUnsupportedStanzaType | The initiating entity has sent a first-level child of the stream that is not supported by the server, either because the receiving entity does not understand the namespace or because the receiving entity does not understand the element name for the applicable namespace (which might be the content namespace declared as the default namespace) |
StreamUnsupportedVersion | The |
data AuthFailure Source
Signals a SASL authentication error condition.
AuthNoAcceptableMechanism [Text] | No mechanism offered by the server was matched by the provided acceptable mechanisms; wraps the mechanisms offered by the server |
AuthSaslFailure SaslFailure | A SASL failure element was encountered |
AuthIllegalCredentials | The credentials provided did not conform to the SASLprep Stringprep profile |
AuthOtherFailure | Other failure; more information is available in the log |
type SaslHandler = (Text, StateT StreamState IO (Either XmppFailure (Maybe AuthFailure)))Source
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.
data ConnectionState Source
Signals the state of the stream connection.
:: ResolvConf | Resolv conf to use (try defaultResolvConf as a default) |
-> TLSParams | TLS parameters to use when securing the connection |
-> String | Host to use when connecting (will be resolved using SRV records) |
-> ErrorT XmppFailure IO StreamHandle |
Connect to an XMPP server and secure the connection with TLS before starting the XMPP streams