paho.mqtt.golang--option.go 源码解析
broker: 指 mqtt 服务器
package mqtt
import (
"crypto/tls"
"net/http"
"net/url"
"regexp"
"strings"
"time"
)
// 允许在重新连接之前更新用户名和密码。函数应该返回当前的用户名和密码。
type CredentialsProvider func() (username string, password string)
// MessageHandler 是一种回调类型，
// 可以设置为在发布到订阅了客户端的主题的消息到达时执行。
type MessageHandler func(Client, Message)
// ConnectionLostHandler是一种回调类型，可以设置为在与MQTT代理意外断开连接时执行。
// 调用Disconnect或ForceDisconnect导致的断开连接不会导致执行OnConnectionLost回调。
type ConnectionLostHandler func(Client, error)
// OnConnectHandler是一个回调，当客户端状态从未连接/已断开变为已连接时，将调用此回调。
// 即 初始连接时和重新连接时执行此函数
type OnConnectHandler func(Client)
// 回调函数
// 初始连接丢失后，在重新连接之前调用
type ReconnectHandler func(Client, *ClientOptions)
// ClientOptions contains configurable options for an Client.
type ClientOptions struct {
Servers []*url.URL // mqtt服务器(broker)的地址
ClientID string // 连接 broker 的客户端的唯一标识符
Username string // 连接 broker 的用户名, 如果 broker 开启了用户名和密码验证时使用
Password string // 连接 broker 的密码
CredentialsProvider CredentialsProvider // 自定义function, 返回值为: (username, password)
CleanSession bool // 是否开启下线后清楚 session
Order bool // 是否顺序发送, true: 同步顺序发送消息, false: 异步发送消息. 发送的消息有可能乱序
WillEnabled bool
WillTopic string // 订阅的主题
WillPayload []byte
WillQos byte //消息类型 0, 1, 2
WillRetained bool //是否保留消息
ProtocolVersion uint // Mqtt 版本号 值=3 使用MQTT 3.1, 值=4使用 MQTT 3.1.1
protocolVersionExplicit bool //是否设定了 mqtt 版本
TLSConfig *tls.Config // tls 加密配置
KeepAlive int64 //向代理发送PING请求之前客户端应等待的时间（以秒为单位）
PingTimeout time.Duration //向代理发送PING请求之后客户端确定连接丢失之前等待的时间（以秒为单位）。默认值为10秒。
ConnectTimeout time.Duration //在尝试打开与MQTT服务器的连接之前客户端超时和错误尝试之前等待的时间。持续时间为0永远不会超时。默认30秒。当前仅可用于TCP / TLS连接。
MaxReconnectInterval time.Duration //连接断开后两次尝试重新连接之间等待的最长时间
AutoReconnect bool //SetAutoReconnect设置在丢失连接时是否应使用自动重新连接逻辑，即使禁用该连接仍会调用ConnectionLostHandler
ConnectRetryInterval time.Duration //如果ConnectRetry为TRUE，则在最初连接时两次连接尝试之间要等待的时间
//配置在失败的情况下connect函数是否将自动重试连接（当为true时，Connect函数返回的令牌在连接建立或被取消之前不会完成）
// 如果ConnectRetry为true，则应在OnConnect处理程序中请求订阅
//将其设置为TRUE允许在建立连接之前发布消息
ConnectRetry bool
Store Store // 提供消息持久性的实现
DefaultPublishHandler MessageHandler
OnConnect OnConnectHandler //可以设置为在发布到订阅了客户端的主题的消息到达时执行。
OnConnectionLost ConnectionLostHandler //与MQTT代理意外断开连接时执行
OnReconnecting ReconnectHandler //初始连接丢失后，在重新连接之前调用
WriteTimeout time.Duration //发布消息阻塞时间, 0: 永远不超时
MessageChannelDepth uint // 作废.
ResumeSubs bool // 将在连接时启用存储的（取消）订阅消息的恢复，但如果CleanSession为false则不重新连接。否则，这些消息将被丢弃。
HTTPHeaders http.Header //websocket 使用
}
// NewClientOptions will create a new ClientClientOptions type with some
// default values.
// Port: 1883
// CleanSession: True
// Order: True
// KeepAlive: 30 (seconds)
// ConnectTimeout: 30 (seconds)
// MaxReconnectInterval 10 (minutes)
// AutoReconnect: True
func NewClientOptions() *ClientOptions {
o := &ClientOptions{
Servers: nil,
ClientID: "",
Username: "",
Password: "",
CleanSession: true,
Order: true,
WillEnabled: false,
WillTopic: "",
WillPayload: nil,
WillQos: 0,
WillRetained: false,
ProtocolVersion: 0,
protocolVersionExplicit: false,
KeepAlive: 30,
PingTimeout: 10 * time.Second,
ConnectTimeout: 30 * time.Second,
MaxReconnectInterval: 10 * time.Minute,
AutoReconnect: true,
ConnectRetryInterval: 30 * time.Second,
ConnectRetry: false,
Store: nil,
OnConnect: nil,
OnConnectionLost: DefaultConnectionLostHandler,
WriteTimeout: 0, // 0 represents timeout disabled
ResumeSubs: false,
HTTPHeaders: make(map[string][]string),
}
return o
}
// AddBroker adds a broker URI to the list of brokers to be used. The format should be
// scheme://host:port
// Where "scheme" is one of "tcp", "ssl", or "ws", "host" is the ip-address (or hostname)
// and "port" is the port on which the broker is accepting connections.
//
// Default values for hostname is "127.0.0.1", for schema is "tcp://".
//
// An example broker URI would look like: tcp://foobar.com:1883
func (o *ClientOptions) AddBroker(server string) *ClientOptions {
re := regexp.MustCompile(`%(25)?`)
if len(server) > 0 && server[0] == ':' {
server = "127.0.0.1" + server
}
if !strings.Contains(server, "://") {
server = "tcp://" + server
}
server = re.ReplaceAllLiteralString(server, "%25")
brokerURI, err := url.Parse(server)
if err != nil {
ERROR.Println(CLI, "Failed to parse %q broker address: %s", server, err)
return o
}
o.Servers = append(o.Servers, brokerURI)
return o
}
// SetResumeSubs will enable resuming of stored (un)subscribe messages when connecting
// but not reconnecting if CleanSession is false. Otherwise these messages are discarded.
func (o *ClientOptions) SetResumeSubs(resume bool) *ClientOptions {
o.ResumeSubs = resume
return o
}
// SetClientID will set the client id to be used by this client when
// connecting to the MQTT broker. According to the MQTT v3.1 specification,
// a client id must be no longer than 23 characters.
func (o *ClientOptions) SetClientID(id string) *ClientOptions {
o.ClientID = id
return o
}
// SetUsername will set the username to be used by this client when connecting
// to the MQTT broker. Note: without the use of SSL/TLS, this information will
// be sent in plaintext across the wire.
func (o *ClientOptions) SetUsername(u string) *ClientOptions {
o.Username = u
return o
}
// SetPassword will set the password to be used by this client when connecting
// to the MQTT broker. Note: without the use of SSL/TLS, this information will
// be sent in plaintext across the wire.
func (o *ClientOptions) SetPassword(p string) *ClientOptions {
o.Password = p
return o
}
// SetCredentialsProvider will set a method to be called by this client when
// connecting to the MQTT broker that provide the current username and password.
// Note: without the use of SSL/TLS, this information will be sent
// in plaintext across the wire.
func (o *ClientOptions) SetCredentialsProvider(p CredentialsProvider) *ClientOptions {
o.CredentialsProvider = p
return o
}
// SetCleanSession will set the "clean session" flag in the connect message
// when this client connects to an MQTT broker. By setting this flag, you are
// indicating that no messages saved by the broker for this client should be
// delivered. Any messages that were going to be sent by this client before
// diconnecting previously but didn't will not be sent upon connecting to the
// broker.
func (o *ClientOptions) SetCleanSession(clean bool) *ClientOptions {
o.CleanSession = clean
return o
}
// SetOrderMatters will set the message routing to guarantee order within
// each QoS level. By default, this value is true. If set to false,
// this flag indicates that messages can be delivered asynchronously
// from the client to the application and possibly arrive out of order.
func (o *ClientOptions) SetOrderMatters(order bool) *ClientOptions {
o.Order = order
return o
}
// SetTLSConfig will set an SSL/TLS configuration to be used when connecting
// to an MQTT broker. Please read the official Go documentation for more
// information.
func (o *ClientOptions) SetTLSConfig(t *tls.Config) *ClientOptions {
o.TLSConfig = t
return o
}
// SetStore will set the implementation of the Store interface
// used to provide message persistence in cases where QoS levels
// QoS_ONE or QoS_TWO are used. If no store is provided, then the
// client will use MemoryStore by default.
func (o *ClientOptions) SetStore(s Store) *ClientOptions {
o.Store = s
return o
}
// SetKeepAlive will set the amount of time (in seconds) that the client
// should wait before sending a PING request to the broker. This will
// allow the client to know that a connection has not been lost with the
// server.
func (o *ClientOptions) SetKeepAlive(k time.Duration) *ClientOptions {
o.KeepAlive = int64(k / time.Second)
return o
}
// SetPingTimeout will set the amount of time (in seconds) that the client
// will wait after sending a PING request to the broker, before deciding
// that the connection has been lost. Default is 10 seconds.
func (o *ClientOptions) SetPingTimeout(k time.Duration) *ClientOptions {
o.PingTimeout = k
return o
}
// SetProtocolVersion sets the MQTT version to be used to connect to the
// broker. Legitimate values are currently 3 - MQTT 3.1 or 4 - MQTT 3.1.1
func (o *ClientOptions) SetProtocolVersion(pv uint) *ClientOptions {
if (pv >= 3 && pv <= 4) || (pv > 0x80) {
o.ProtocolVersion = pv
o.protocolVersionExplicit = true
}
return o
}
// UnsetWill will cause any set will message to be disregarded.
func (o *ClientOptions) UnsetWill() *ClientOptions {
o.WillEnabled = false
return o
}
// SetWill accepts a string will message to be set. When the client connects,
// it will give this will message to the broker, which will then publish the
// provided payload (the will) to any clients that are subscribed to the provided
// topic.
func (o *ClientOptions) SetWill(topic string, payload string, qos byte, retained bool) *ClientOptions {
o.SetBinaryWill(topic, []byte(payload), qos, retained)
return o
}
// SetBinaryWill accepts a []byte will message to be set. When the client connects,
// it will give this will message to the broker, which will then publish the
// provided payload (the will) to any clients that are subscribed to the provided
// topic.
func (o *ClientOptions) SetBinaryWill(topic string, payload []byte, qos byte, retained bool) *ClientOptions {
o.WillEnabled = true
o.WillTopic = topic
o.WillPayload = payload
o.WillQos = qos
o.WillRetained = retained
return o
}
// SetDefaultPublishHandler sets the MessageHandler that will be called when a message
// is received that does not match any known subscriptions.
func (o *ClientOptions) SetDefaultPublishHandler(defaultHandler MessageHandler) *ClientOptions {
o.DefaultPublishHandler = defaultHandler
return o
}
// SetOnConnectHandler sets the function to be called when the client is connected. Both
// at initial connection time and upon automatic reconnect.
func (o *ClientOptions) SetOnConnectHandler(onConn OnConnectHandler) *ClientOptions {
o.OnConnect = onConn
return o
}
// SetConnectionLostHandler will set the OnConnectionLost callback to be executed
// in the case where the client unexpectedly loses connection with the MQTT broker.
func (o *ClientOptions) SetConnectionLostHandler(onLost ConnectionLostHandler) *ClientOptions {
o.OnConnectionLost = onLost
return o
}
// SetReconnectingHandler sets the OnReconnecting callback to be executed prior
// to the client attempting a reconnect to the MQTT broker.
func (o *ClientOptions) SetReconnectingHandler(cb ReconnectHandler) *ClientOptions {
o.OnReconnecting = cb
return o
}
// SetWriteTimeout puts a limit on how long a mqtt publish should block until it unblocks with a
// timeout error. A duration of 0 never times out. Default 30 seconds
func (o *ClientOptions) SetWriteTimeout(t time.Duration) *ClientOptions {
o.WriteTimeout = t
return o
}
// SetConnectTimeout limits how long the client will wait when trying to open a connection
// to an MQTT server before timing out and erroring the attempt. A duration of 0 never times out.
// Default 30 seconds. Currently only operational on TCP/TLS connections.
func (o *ClientOptions) SetConnectTimeout(t time.Duration) *ClientOptions {
o.ConnectTimeout = t
return o
}
// SetMaxReconnectInterval sets the maximum time that will be waited between reconnection attempts
// when connection is lost
func (o *ClientOptions) SetMaxReconnectInterval(t time.Duration) *ClientOptions {
o.MaxReconnectInterval = t
return o
}
// SetAutoReconnect sets whether the automatic reconnection logic should be used
// when the connection is lost, even if disabled the ConnectionLostHandler is still
// called
func (o *ClientOptions) SetAutoReconnect(a bool) *ClientOptions {
o.AutoReconnect = a
return o
}
// SetConnectRetryInterval sets the time that will be waited between connection attempts
// when initially connecting if ConnectRetry is TRUE
func (o *ClientOptions) SetConnectRetryInterval(t time.Duration) *ClientOptions {
o.ConnectRetryInterval = t
return o
}
// SetConnectRetry sets whether the connect function will automatically retry the connection
// in the event of a failure (when true the token returned by the Connect function will
// not complete until the connection is up or it is cancelled)
// If ConnectRetry is true then subscriptions should be requested in OnConnect handler
// Setting this to TRUE permits mesages to be published before the connection is established
func (o *ClientOptions) SetConnectRetry(a bool) *ClientOptions {
o.ConnectRetry = a
return o
}
// SetMessageChannelDepth DEPRECATED The value set here no longer has any effect, this function
// remains so the API is not altered.
func (o *ClientOptions) SetMessageChannelDepth(s uint) *ClientOptions {
o.MessageChannelDepth = s
return o
}
// SetHTTPHeaders sets the additional HTTP headers that will be sent in the WebSocket
// opening handshake.
func (o *ClientOptions) SetHTTPHeaders(h http.Header) *ClientOptions {
o.HTTPHeaders = h
return o
}
