Portability | portable |
---|---|
Stability | unstable |
Maintainer | info@jonkri.com |
Safe Haskell | None |
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.
- newtype Stream = Stream {}
- data StreamConfiguration = StreamConfiguration {
- preferredLang :: !(Maybe LangTag)
- toJid :: !(Maybe (Jid, Bool))
- connectionDetails :: ConnectionDetails
- resolvConf :: ResolvConf
- establishSession :: Bool
- tlsBehaviour :: TlsBehaviour
- tlsParams :: TLSParams
- data StreamState = StreamState {
- streamConnectionState :: !ConnectionState
- streamHandle :: StreamHandle
- streamEventSource :: Source IO Event
- streamFeatures :: !StreamFeatures
- streamAddress :: !(Maybe Text)
- streamFrom :: !(Maybe Jid)
- streamId :: !(Maybe Text)
- streamLang :: !(Maybe LangTag)
- streamJid :: !(Maybe Jid)
- streamConfiguration :: StreamConfiguration
- data StreamHandle = StreamHandle {
- streamSend :: ByteString -> IO Bool
- streamReceive :: Int -> IO ByteString
- streamFlush :: IO ()
- streamClose :: IO ()
- data StreamFeatures = StreamFeatures {
- streamTls :: !(Maybe Bool)
- streamSaslMechanisms :: ![Text]
- rosterVer :: !(Maybe Bool)
- streamOtherFeatures :: ![Element]
- openStream :: HostName -> StreamConfiguration -> IO (Either XmppFailure Stream)
- withStream :: StateT StreamState IO a -> Stream -> IO a
- tls :: Stream -> IO (Either XmppFailure ())
- auth :: [SaslHandler] -> Maybe Text -> Stream -> IO (Either XmppFailure (Maybe AuthFailure))
- pushStanza :: Stanza -> Stream -> IO (Either XmppFailure Bool)
- pullStanza :: Stream -> IO (Either XmppFailure Stanza)
- pushIQ :: Text -> Maybe Jid -> IQRequestType -> Maybe LangTag -> Element -> Stream -> IO (Either XmppFailure (Either IQError IQResult))
- type SaslHandler = (Text, StateT StreamState IO (Either XmppFailure (Maybe AuthFailure)))
- data Stanza
- = IQRequestS !IQRequest
- | IQResultS !IQResult
- | IQErrorS !IQError
- | MessageS !Message
- | MessageErrorS !MessageError
- | PresenceS !Presence
- | PresenceErrorS !PresenceError
- data TlsBehaviour
- = RequireTls
- | PreferTls
- | PreferPlain
- | RefuseTls
Documentation
data StreamConfiguration Source
Configuration settings related to the stream.
StreamConfiguration | |
|
data StreamState Source
StreamState | |
|
data StreamHandle Source
Defines operations for sending, receiving, flushing, and closing on a stream.
StreamHandle | |
|
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.
The Xmpp communication primities (Message, Presence and Info/Query) are called stanzas.
data TlsBehaviour Source
How the client should behave in regards to TLS.
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. |