Copyright	(c) Dustin Sallings 2019
License	BSD3
Maintainer	dustin@spy.net
Stability	experimental
Safe Haskell	None
Language	Haskell2010

Network.MQTT.Client

Contents

Configuring the client.
Running and waiting for the client.
General client interactions.

Description

An MQTT protocol client

Both MQTT 3.1.1 and MQTT 5.0 are supported.

Synopsis

data MQTTConfig = MQTTConfig {
- _hostname :: String
- _port :: Int
- _connID :: String
- _username :: Maybe String
- _password :: Maybe String
- _cleanSession :: Bool
- _lwt :: Maybe LastWill
- _msgCB :: Maybe (MQTTClient -> Topic -> ByteString -> [Property] -> IO ())
- _protocol :: ProtocolLevel
- _connProps :: [Property]
}
data MQTTClient
data QoS
- = QoS0
- | QoS1
- | QoS2
type Topic = Text
mqttConfig :: MQTTConfig
mkLWT :: Topic -> ByteString -> Bool -> LastWill
data LastWill = LastWill {
- _willRetain :: Bool
- _willQoS :: QoS
- _willTopic :: ByteString
- _willMsg :: ByteString
- _willProps :: [Property]
}
data ProtocolLevel
- = Protocol311
- | Protocol50
data Property
- = PropPayloadFormatIndicator Word8
- | PropMessageExpiryInterval Word32
- | PropContentType ByteString
- | PropResponseTopic ByteString
- | PropCorrelationData ByteString
- | PropSubscriptionIdentifier Int
- | PropSessionExpiryInterval Word32
- | PropAssignedClientIdentifier ByteString
- | PropServerKeepAlive Word16
- | PropAuthenticationMethod ByteString
- | PropAuthenticationData ByteString
- | PropRequestProblemInformation Word8
- | PropWillDelayInterval Word32
- | PropRequestResponseInformation Word8
- | PropResponseInformation ByteString
- | PropServerReference ByteString
- | PropReasonString ByteString
- | PropReceiveMaximum Word16
- | PropTopicAliasMaximum Word16
- | PropTopicAlias Word16
- | PropMaximumQoS Word8
- | PropRetainAvailable Word8
- | PropUserProperty ByteString ByteString
- | PropMaximumPacketSize Word32
- | PropWildcardSubscriptionAvailable Word8
- | PropSubscriptionIdentifierAvailable Word8
- | PropSharedSubscriptionAvailable Word8
data SubOptions = SubOptions {
- _retainHandling :: RetainHandling
- _retainAsPublished :: Bool
- _noLocal :: Bool
- _subQoS :: QoS
}
defaultSubOptions :: SubOptions
runClient :: MQTTConfig -> IO MQTTClient
runClientTLS :: MQTTConfig -> IO MQTTClient
waitForClient :: MQTTClient -> IO (Either SomeException ())
connectURI :: MQTTConfig -> URI -> IO MQTTClient
svrProps :: MQTTClient -> IO [Property]
disconnect :: MQTTClient -> DiscoReason -> [Property] -> IO ()
normalDisconnect :: MQTTClient -> IO ()
subscribe :: MQTTClient -> [(Filter, SubOptions)] -> IO ([Either SubErr QoS], [Property])
unsubscribe :: MQTTClient -> [Filter] -> [Property] -> IO ()
publish :: MQTTClient -> Topic -> ByteString -> Bool -> IO ()
publishq :: MQTTClient -> Topic -> ByteString -> Bool -> QoS -> [Property] -> IO ()
pubAliased :: MQTTClient -> Topic -> ByteString -> Bool -> QoS -> [Property] -> IO ()

Configuring the client.

data MQTTConfig Source #

Configuration for setting up an MQTT client.

Constructors

MQTTConfig

Fields

_hostname :: String
Host to connect to.
_port :: Int
Port number.
_connID :: String
Unique connection ID (required).
_username :: Maybe String
Optional username.
_password :: Maybe String
Optional password.
_cleanSession :: Bool
False if a session should be reused.
_lwt :: Maybe LastWill
LastWill message to be sent on client disconnect.
_msgCB :: Maybe (MQTTClient -> Topic -> ByteString -> [Property] -> IO ())
Callback for incoming messages.
_protocol :: ProtocolLevel
Protocol to use for the connection.
_connProps :: [Property]
Properties to send to the broker in the CONNECT packet.

data MQTTClient Source #

The MQTT client. A client may be built using either runClient or runClientTLS. For example:

  mc <- runClient mqttConfig{}
  publish mc "some/topic" "some message" False

data QoS Source #

QoS values for publishing and subscribing.

Constructors

QoS0
QoS1
QoS2

Instances

Bounded QoS Source #
Instance details Defined in Network.MQTT.Types Methods minBound :: QoS # maxBound :: QoS #
Enum QoS Source #
Instance details Defined in Network.MQTT.Types Methods succ :: QoS -> QoS # pred :: QoS -> QoS # toEnum :: Int -> QoS # fromEnum :: QoS -> Int # enumFrom :: QoS -> [QoS] # enumFromThen :: QoS -> QoS -> [QoS] # enumFromTo :: QoS -> QoS -> [QoS] # enumFromThenTo :: QoS -> QoS -> QoS -> [QoS] #
Eq QoS Source #
Instance details Defined in Network.MQTT.Types Methods (==) :: QoS -> QoS -> Bool # (/=) :: QoS -> QoS -> Bool #
Show QoS Source #
Instance details Defined in Network.MQTT.Types Methods showsPrec :: Int -> QoS -> ShowS # show :: QoS -> String # showList :: [QoS] -> ShowS #

type Topic = Text Source #

An MQTT topic.

mqttConfig :: MQTTConfig Source #

A default MQTTConfig. A _connID should be provided by the client in the returned config, but the defaults should work for testing. In MQTTv5, an empty connection ID may be sent and the server may assign an identifier for you and return it in the PropAssignedClientIdentifier property.

mkLWT :: Topic -> ByteString -> Bool -> LastWill Source #

A convenience method for creating a LastWill.

data LastWill Source #

An MQTT Will message.

Constructors

LastWill
Fields _willRetain :: Bool _willQoS :: QoS _willTopic :: ByteString _willMsg :: ByteString _willProps :: [Property]

Instances

Eq LastWill Source #
Instance details Defined in Network.MQTT.Types Methods (==) :: LastWill -> LastWill -> Bool # (/=) :: LastWill -> LastWill -> Bool #
Show LastWill Source #
Instance details Defined in Network.MQTT.Types Methods showsPrec :: Int -> LastWill -> ShowS # show :: LastWill -> String # showList :: [LastWill] -> ShowS #

data ProtocolLevel Source #

MQTT Protocol Levels

Constructors

Protocol311	MQTT 3.1.1
Protocol50	MQTT 5.0

Instances

Bounded ProtocolLevel Source #
Instance details Defined in Network.MQTT.Types Methods minBound :: ProtocolLevel # maxBound :: ProtocolLevel #
Enum ProtocolLevel Source #
Instance details Defined in Network.MQTT.Types Methods succ :: ProtocolLevel -> ProtocolLevel # pred :: ProtocolLevel -> ProtocolLevel # toEnum :: Int -> ProtocolLevel # fromEnum :: ProtocolLevel -> Int # enumFrom :: ProtocolLevel -> [ProtocolLevel] # enumFromThen :: ProtocolLevel -> ProtocolLevel -> [ProtocolLevel] # enumFromTo :: ProtocolLevel -> ProtocolLevel -> [ProtocolLevel] # enumFromThenTo :: ProtocolLevel -> ProtocolLevel -> ProtocolLevel -> [ProtocolLevel] #
Eq ProtocolLevel Source #
Instance details Defined in Network.MQTT.Types Methods (==) :: ProtocolLevel -> ProtocolLevel -> Bool # (/=) :: ProtocolLevel -> ProtocolLevel -> Bool #
Show ProtocolLevel Source #
Instance details Defined in Network.MQTT.Types Methods showsPrec :: Int -> ProtocolLevel -> ShowS # show :: ProtocolLevel -> String # showList :: [ProtocolLevel] -> ShowS #
ByteMe ProtocolLevel Source #
Instance details Defined in Network.MQTT.Types Methods toBytes :: ProtocolLevel -> ProtocolLevel -> [Word8] toByteString :: ProtocolLevel -> ProtocolLevel -> ByteString Source #

data Property Source #

Constructors

PropPayloadFormatIndicator Word8
PropMessageExpiryInterval Word32
PropContentType ByteString
PropResponseTopic ByteString
PropCorrelationData ByteString
PropSubscriptionIdentifier Int
PropSessionExpiryInterval Word32
PropAssignedClientIdentifier ByteString
PropServerKeepAlive Word16
PropAuthenticationMethod ByteString
PropAuthenticationData ByteString
PropRequestProblemInformation Word8
PropWillDelayInterval Word32
PropRequestResponseInformation Word8
PropResponseInformation ByteString
PropServerReference ByteString
PropReasonString ByteString
PropReceiveMaximum Word16
PropTopicAliasMaximum Word16
PropTopicAlias Word16
PropMaximumQoS Word8
PropRetainAvailable Word8
PropUserProperty ByteString ByteString
PropMaximumPacketSize Word32
PropWildcardSubscriptionAvailable Word8
PropSubscriptionIdentifierAvailable Word8
PropSharedSubscriptionAvailable Word8

Instances

Eq Property Source #
Instance details Defined in Network.MQTT.Types Methods (==) :: Property -> Property -> Bool # (/=) :: Property -> Property -> Bool #
Show Property Source #
Instance details Defined in Network.MQTT.Types Methods showsPrec :: Int -> Property -> ShowS # show :: Property -> String # showList :: [Property] -> ShowS #
ByteMe Property Source #
Instance details Defined in Network.MQTT.Types Methods toBytes :: ProtocolLevel -> Property -> [Word8] toByteString :: ProtocolLevel -> Property -> ByteString Source #

data SubOptions Source #

Constructors

SubOptions
Fields _retainHandling :: RetainHandling _retainAsPublished :: Bool _noLocal :: Bool _subQoS :: QoS

Instances

Eq SubOptions Source #
Instance details Defined in Network.MQTT.Types Methods (==) :: SubOptions -> SubOptions -> Bool # (/=) :: SubOptions -> SubOptions -> Bool #
Show SubOptions Source #
Instance details Defined in Network.MQTT.Types Methods showsPrec :: Int -> SubOptions -> ShowS # show :: SubOptions -> String # showList :: [SubOptions] -> ShowS #
ByteMe SubOptions Source #
Instance details Defined in Network.MQTT.Types Methods toBytes :: ProtocolLevel -> SubOptions -> [Word8] toByteString :: ProtocolLevel -> SubOptions -> ByteString Source #

defaultSubOptions :: SubOptions Source #

Running and waiting for the client.

runClient :: MQTTConfig -> IO MQTTClient Source #

Set up and run a client from the given config.

runClientTLS :: MQTTConfig -> IO MQTTClient Source #

Set up and run a client connected via TLS.

waitForClient :: MQTTClient -> IO (Either SomeException ()) Source #

Wait for a client to terminate its connection.

connectURI :: MQTTConfig -> URI -> IO MQTTClient Source #

Connect to an MQTT server by URI. Currently only mqtt and mqtts URLs are supported. The host, port, username, and password will be derived from the URI and the values supplied in the config will be ignored.

svrProps :: MQTTClient -> IO [Property] Source #

Get the list of properties that were sent from the broker at connect time.

disconnect :: MQTTClient -> DiscoReason -> [Property] -> IO () Source #

Disconnect from the MQTT server.

normalDisconnect :: MQTTClient -> IO () Source #

Disconnect with DiscoNormalDisconnection and no properties.

General client interactions.

subscribe :: MQTTClient -> [(Filter, SubOptions)] -> IO ([Either SubErr QoS], [Property]) Source #

Subscribe to a list of topic filters with their respective QoSes. The accepted QoSes are returned in the same order as requested.

unsubscribe :: MQTTClient -> [Filter] -> [Property] -> IO () Source #

Unsubscribe from a list of topic filters.

publish Source #

Arguments

:: MQTTClient
-> Topic	Topic
-> ByteString	Message body
-> Bool	Retain flag
-> IO ()

Publish a message (QoS 0).

publishq Source #

Arguments

:: MQTTClient
-> Topic	Topic
-> ByteString	Message body
-> Bool	Retain flag
-> QoS	QoS
-> [Property]	Properties
-> IO ()

Publish a message with the specified QoS and Properties list.

pubAliased Source #

Arguments

:: MQTTClient
-> Topic	Topic
-> ByteString	Message body
-> Bool	Retain flag
-> QoS	QoS
-> [Property]	Properties
-> IO ()

Publish a message with the specified QoS and Properties list. If possible, use an alias to shorten the message length. The alias list is managed by the client in a first-come, first-served basis, so if you use this with more properties than the broker allows, only the first N (up to TopicAliasMaximum, as specified by the broker at connect time) will be aliased.

This is safe to use as a general publish mechanism, as it will default to not aliasing whenver there's not already an alias and we can't create any more.