client

Documentation

Overview

Package client provides MQTT client.

Index

• Variables
• type Client
  • func Connect(p Param) (Client, error)
• type DisconnectedFunc
• type Message
• type Options
• type Param
• type PublishedFunc
• type QoS
  • func (q QoS) String() string
• type Reason
  • func (r Reason) Error() string
• type SubscribeError
  • func (e *SubscribeError) Error() string
• type Topic
• type UnsubscribeError
  • func (e *UnsubscribeError) Error() string
• type Will

Variables

var (
	// ErrUnknownProtocol indicates connect adddress includes unknown protocol.
	ErrUnknownProtocol = errors.New("unknown protocol")

	// ErrTerminated indicates the operation is terminated.
	ErrTerminated = errors.New("terminated")
)

var DefaultOptions = &Options{
	Version:      4,
	CleanSession: true,
	KeepAlive:    30,
}

DefaultOptions represents default values which used for when Connect()'s opts argument is nil.

Types

type Client

type Client interface {
	// Disconnect shutdown MQTT connection.
	Disconnect(force bool) error

	// Ping sends a PING packet.
	Ping() error

	// Subscribe subsribes to topics.
	Subscribe(topics []Topic) error

	// Unsubscribe unsubscribes from topics.
	Unsubscribe(topics []string) error

	// Publish publishes a message to MQTT broker.
	Publish(qos QoS, retain bool, topic string, msg []byte) error

	// Read returns a message if it was available.
	// If any messages are unavailable, this blocks until message would be
	// available when block is true, and this returns nil when block is false.
	Read(block bool) (*Message, error)
}

Client is a MQTT client.

func Connect

func Connect(p Param) (Client, error)

Connect connects to MQTT broker and returns a Client.

type DisconnectedFunc

type DisconnectedFunc func(reason error, param Param)

DisconnectedFunc is called when a connection was lost. reason can be one of Reason or other errors.

type Message

type Message struct {
	Topic string
	Body  []byte
}

Message represents a MQTT's published message.

type Options

type Options struct {
	Version      uint8   // MQTT's protocol version 3 or 4 (fallback to 4)
	Username     *string // username to connect (option)
	Password     *string // password to connect (option)
	CleanSession bool
	KeepAlive    uint16
	Will         *Will

	// DisableAutoKeepAlive disables auto ping to keep alive.
	DisableAutoKeepAlive bool

	ConnectTimeout time.Duration
	TLSConfig      *tls.Config

	WSOrigin string

	Logger *log.Logger
}

Options represents connect options

type Param

type Param struct {
	// Addr is URL to connect like "tcp://192.168.0.1:1883".
	Addr string

	// ID is used as MQTT's client ID.
	ID string

	// OnPublish is called when receive a PUBLISH message with independed
	// goroutine.  If it is omitted, received messages are stored into buffer.
	OnPublish PublishedFunc

	// OnDisconnect is called when connection is disconnected.
	OnDisconnect DisconnectedFunc

	// Options is option parameters for connection.
	Options *Options
}

Param represents connection parameters for MQTT client.

type PublishedFunc

type PublishedFunc func(m *Message)

PublishedFunc is called when receive a message.

type QoS

type QoS uint8

QoS represents QoS levels of MQTT. Invalid values are treated as AtMostOnce.

const (
	// AtMostOnce represents "fire and forget" (<=1).
	AtMostOnce QoS = iota

	// AtLeastOnce represents "acknowledged delivery" (>=1).
	AtLeastOnce

	// ExactlyOnce represents "assured delivery" (=1).
	ExactlyOnce

	// Failure indicates "subscription failed".
	Failure = 0x80
)

func (QoS) String

func (q QoS) String() string

type Reason

type Reason int

Reason represents reason of disconnection.

const (
	// Explicitly shows called Disconnect() explicitly.
	Explicitly Reason = iota

	// Timeout shows by timeout.
	Timeout
)

func (Reason) Error

func (r Reason) Error() string

type SubscribeError

type SubscribeError struct {
	// MismatchPacketID is set true, when detect mismatch of packet ID in ACK.
	MismatchPacketID    bool
	MismatchResultCount bool
	RequestedQoS        []QoS
	ResultQoS           []QoS
}

SubscribeError is detailed error for Subscribe().

func (*SubscribeError) Error

func (e *SubscribeError) Error() string

type Topic

type Topic struct {

	// Filter is a filter string for topics which interested in.
	Filter string

	// QoS is required QoS for this topic filter.
	QoS QoS
}

Topic represents a topic filter fanned in.

type UnsubscribeError

type UnsubscribeError struct {
	// MismatchPacketID is set true, when detect mismatch of packet ID in ACK.
	MismatchPacketID bool
}

UnsubscribeError is detailed error for Unsubscribe()

func (*UnsubscribeError) Error

func (e *UnsubscribeError) Error() string

type Will

type Will struct {
	QoS     QoS
	Retain  bool
	Topic   string
	Message string
}

Will represents MQTT's will message.