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

Network.Xmpp.Internal

Description

This module allows for low-level access to Pontarius XMPP. Generally, the Network.Xmpp module should be used instead.

The Stream object provides the most low-level access to the XMPP stream: a simple and single-threaded interface which exposes the conduit Event source, as well as the input and output byte streams. Custom stateful Stream functions can be executed using withStream.

The TLS, SASL, and Session functionalities of Pontarius XMPP are built on top of this API.

Synopsis

Documentation

newtype Stream Source

Constructors

Stream
Fields unStream :: TMVar StreamState

data StreamConfiguration Source

Configuration settings related to the stream.

Constructors

StreamConfiguration

Fields

preferredLang :: !(Maybe LangTag): Default language when no language tag is set
toJid :: !(Maybe (Jid, Bool)): JID to include in the stream element's to attribute when the connection is secured; if the boolean is set to True, then the JID is also included when the ConnectionState is Plain
connectionDetails :: ConnectionDetails: By settings this field, clients can specify the network interface to use, override the SRV lookup of the realm, as well as specify the use of a non-standard port when connecting by IP or connecting to a domain without SRV records.
resolvConf :: ResolvConf: DNS resolver configuration
establishSession :: Bool: Whether or not to perform the legacy session bind as defined in the (outdated) RFC 3921 specification
tlsBehaviour :: TlsBehaviour: How the client should behave in regards to TLS.
tlsParams :: TLSParams: Settings to be used for TLS negotitation

Instances

Default StreamConfiguration

data StreamState Source

Constructors

StreamState

Fields

streamConnectionState :: !ConnectionState: State of the stream - Closed, Plain, or Secured
streamHandle :: StreamHandle: Functions to send, receive, flush, and close the stream
streamEventSource :: Source IO Event: Event conduit source, and its associated finalizer
streamFeatures :: !StreamFeatures: Stream features advertised by the server
streamAddress :: !(Maybe Text): The hostname or IP specified for the connection
streamFrom :: !(Maybe Jid): The hostname specified in the server's stream element's from attribute
streamId :: !(Maybe Text): The identifier specified in the server's stream element's id attribute
streamLang :: !(Maybe LangTag): The language tag value specified in the server's stream element's langtag attribute; will be a Just value once connected to the server TODO: Verify
streamJid :: !(Maybe Jid): Our JID as assigned by the server
streamConfiguration :: StreamConfiguration: Configuration settings for the stream

data StreamHandle Source

Defines operations for sending, receiving, flushing, and closing on a stream.

Constructors

StreamHandle
Fields streamSend :: ByteString -> IO Bool Sends may not interleave streamReceive :: Int -> IO ByteString streamFlush :: IO () streamClose :: IO ()

data StreamFeatures Source

Constructors

StreamFeatures
Fields streamTls :: !(Maybe Bool) streamSaslMechanisms :: ![Text] rosterVer :: !(Maybe Bool) `Nothing` for no roster versioning, `Just False` for roster versioning and `Just True` when the server sends the non-standard optional element (observed with prosody). streamOtherFeatures :: ![Element]

Instances

Show StreamFeatures

openStream :: HostName -> StreamConfiguration -> IO (Either XmppFailure Stream)Source

Connects to the XMPP server and opens the XMPP stream against the given realm.

withStream :: StateT StreamState IO a -> Stream -> IO aSource

tls :: Stream -> IO (Either XmppFailure ())Source

Checks for TLS support and run starttls procedure if applicable

auth :: [SaslHandler] -> Maybe Text -> Stream -> IO (Either XmppFailure (Maybe AuthFailure))Source

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

pushStanza :: Stanza -> Stream -> IO (Either XmppFailure Bool)Source

Encode and send stanza

pullStanza :: Stream -> IO (Either XmppFailure Stanza)Source

Pulls a stanza (or stream error) from the stream.

pushIQ :: Text -> Maybe Jid -> IQRequestType -> Maybe LangTag -> Element -> Stream -> IO (Either XmppFailure (Either IQError IQResult))Source

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 Stanza Source

The Xmpp communication primities (Message, Presence and Info/Query) are called stanzas.

Constructors

IQRequestS !IQRequest
IQResultS !IQResult
IQErrorS !IQError
MessageS !Message
MessageErrorS !MessageError
PresenceS !Presence
PresenceErrorS !PresenceError

Instances

Show Stanza

data TlsBehaviour Source

How the client should behave in regards to TLS.

Constructors

RequireTls	Require the use of TLS; disconnect if it's not offered.
PreferTls	Negotitate TLS if it's available.
PreferPlain	Negotitate TLS only if the server requires it
RefuseTls	Never secure the stream with TLS.