Documentation
¶
Overview ¶
Package packet implements functionality for encoding and decoding MQTT packets.
Example ¶
/* Packet Encoding */
// Create new packet.
pkt1 := NewConnect()
pkt1.Username = "gomqtt"
pkt1.Password = "amazing!"
// Allocate buffer.
buf := make([]byte, pkt1.Len())
// Encode the packet.
if _, err := pkt1.Encode(buf); err != nil {
panic(err) // error while encoding
}
/* Packet Decoding */
// Detect packet.
l, mt := DetectPacket(buf)
// Check length
if l == 0 {
return // buffer not complete yet
}
// Create packet.
pkt2, err := mt.New()
if err != nil {
panic(err) // packet type is invalid
}
// Decode packet.
_, err = pkt2.Decode(buf)
if err != nil {
panic(err) // there was an error while decoding
}
switch pkt2.Type() {
case CONNECT:
c := pkt2.(*Connect)
fmt.Println(c.Username)
fmt.Println(c.Password)
}
Output: gomqtt amazing!
Index ¶
- Constants
- Variables
- func Fuzz(data []byte) int
- type Connack
- type ConnackCode
- type Connect
- type Decoder
- type Disconnect
- type Encoder
- type Error
- type Generic
- type ID
- type Message
- type Pingreq
- type Pingresp
- type Puback
- type Pubcomp
- type Publish
- type Pubrec
- type Pubrel
- type QOS
- type Stream
- type Suback
- type Subscribe
- type Subscription
- type Type
- type Unsuback
- type Unsubscribe
Examples ¶
Constants ¶
const ( Version31 byte = 3 Version311 byte = 4 )
The supported MQTT versions.
Variables ¶
var ErrDetectionOverflow = errors.New("detection overflow")
ErrDetectionOverflow is returned by the Decoder if the next packet couldn't be detected from the initial header bytes.
var ErrInvalidPacketType = errors.New("invalid packet type")
ErrInvalidPacketType is returned by New if the packet type is invalid.
var ErrReadLimitExceeded = errors.New("read limit exceeded")
ErrReadLimitExceeded can be returned during a Receive if the connection exceeded its read limit.
Functions ¶
func Fuzz ¶
Fuzz is a basic fuzzing test that works with https://github.com/dvyukov/go-fuzz:
$ go-fuzz-build github.com/gomqtt/packet $ go-fuzz -bin=./packet-fuzz.zip -workdir=./fuzz
Types ¶
type Connack ¶ added in v0.7.1
type Connack struct {
// The SessionPresent flag enables a client to establish whether the
// client and server have a consistent view about whether there is already
// stored session state.
SessionPresent bool
// If a well-formed Connect packet is received by the server, but the server
// is unable to process it for some reason, then the server should attempt
// to send a Connack containing a non-zero ReturnCode.
ReturnCode ConnackCode
}
A Connack packet is sent by the server in response to a Connect packet received from a client.
func NewConnack ¶ added in v0.7.1
func NewConnack() *Connack
NewConnack creates a new Connack packet.
func (*Connack) Decode ¶ added in v0.7.1
Decode reads from the byte slice argument. It returns the total number of bytes decoded, and whether there have been any errors during the process.
func (*Connack) Encode ¶ added in v0.7.1
Encode writes the packet bytes into the byte slice from the argument. It returns the number of bytes encoded and whether there's any errors along the way. If there is an error, the byte slice should be considered invalid.
type ConnackCode ¶
type ConnackCode uint8
The ConnackCode represents the return code in a Connack packet.
const ( ConnectionAccepted ConnackCode = iota InvalidProtocolVersion IdentifierRejected BadUsernameOrPassword NotAuthorized )
All available ConnackCodes.
func (ConnackCode) String ¶ added in v0.9.0
func (cc ConnackCode) String() string
String returns the corresponding error string for the ConnackCode.
func (ConnackCode) Valid ¶
func (cc ConnackCode) Valid() bool
Valid checks if the ConnackCode is valid.
type Connect ¶ added in v0.7.1
type Connect struct {
// The client's client id.
ClientID string
// The keep alive value.
KeepAlive uint16
// The authentication username.
Username string
// The authentication password.
Password string
// The clean session flag.
CleanSession bool
// The will message.
Will *Message
// The MQTT version 3 or 4 (defaults to 4 when 0).
Version byte
}
A Connect packet is sent by a client to the server after a network connection has been established.
func NewConnect ¶ added in v0.7.1
func NewConnect() *Connect
NewConnect creates a new Connect packet.
func (*Connect) Decode ¶ added in v0.7.1
Decode reads from the byte slice argument. It returns the total number of bytes decoded, and whether there have been any errors during the process.
func (*Connect) Encode ¶ added in v0.7.1
Encode writes the packet bytes into the byte slice from the argument. It returns the number of bytes encoded and whether there's any errors along the way. If there is an error, the byte slice should be considered invalid.
type Decoder ¶
type Decoder struct {
// contains filtered or unexported fields
}
A Decoder wraps a Reader and continuously decodes packets.
func (*Decoder) SetReadLimit ¶ added in v0.13.0
SetReadLimit will set the read limit. Packets with a length above that limit will cause the ErrReadLimitExceeded error.
type Disconnect ¶ added in v0.7.1
type Disconnect struct{}
A Disconnect packet is sent from the client to the server. It indicates that the client is disconnecting cleanly.
func NewDisconnect ¶ added in v0.7.1
func NewDisconnect() *Disconnect
NewDisconnect creates a new Disconnect packet.
func (*Disconnect) Decode ¶ added in v0.7.1
func (d *Disconnect) Decode(src []byte) (int, error)
Decode reads from the byte slice argument. It returns the total number of bytes decoded, and whether there have been any errors during the process.
func (*Disconnect) Encode ¶ added in v0.7.1
func (d *Disconnect) Encode(dst []byte) (int, error)
Encode writes the packet bytes into the byte slice from the argument. It returns the number of bytes encoded and whether there's any errors along the way. If there is an error, the byte slice should be considered invalid.
func (*Disconnect) Len ¶ added in v0.7.1
func (d *Disconnect) Len() int
Len returns the byte length of the encoded packet.
func (*Disconnect) String ¶ added in v0.7.1
func (d *Disconnect) String() string
String returns a string representation of the packet.
func (*Disconnect) Type ¶ added in v0.7.1
func (d *Disconnect) Type() Type
Type returns the packets type.
type Encoder ¶
type Encoder struct {
// contains filtered or unexported fields
}
An Encoder wraps a writer and continuously encodes packets.
func (*Encoder) SetMaxWriteDelay ¶ added in v0.13.0
SetMaxWriteDelay will set the maximum amount of time allowed to pass until an asynchronous write is flushed.
type Error ¶ added in v0.9.0
type Error struct {
Type Type
// contains filtered or unexported fields
}
Error represents decoding and encoding errors.
type Generic ¶ added in v0.7.1
type Generic interface {
// Type returns the packets type.
Type() Type
// Len returns the byte length of the encoded packet.
Len() int
// Decode reads from the byte slice argument. It returns the total number of
// bytes decoded, and whether there have been any errors during the process.
Decode(src []byte) (int, error)
// Encode writes the packet bytes into the byte slice from the argument. It
// returns the number of bytes encoded and whether there's any errors along
// the way. If there is an error, the byte slice should be considered invalid.
Encode(dst []byte) (int, error)
// String returns a string representation of the packet.
String() string
}
Generic is an MQTT control packet that can be encoded to a buffer or decoded from a buffer.
type ID ¶ added in v0.2.0
type ID uint16
ID is the type used to store packet ids.
type Message ¶
type Message struct {
// The Topic of the message.
Topic string
// The Payload of the message.
Payload []byte
// The QOS indicates the level of assurance for delivery.
QOS QOS
// If the Retain flag is set to true, the server must store the message,
// so that it can be delivered to future subscribers whose subscriptions
// match its topic name.
Retain bool
}
A Message bundles data that is published between brokers and clients.
type Pingreq ¶ added in v0.7.1
type Pingreq struct{}
A Pingreq packet is sent from a client to the server.
func NewPingreq ¶ added in v0.7.1
func NewPingreq() *Pingreq
NewPingreq creates a new Pingreq packet.
func (*Pingreq) Decode ¶ added in v0.7.1
Decode reads from the byte slice argument. It returns the total number of bytes decoded, and whether there have been any errors during the process.
func (*Pingreq) Encode ¶ added in v0.7.1
Encode writes the packet bytes into the byte slice from the argument. It returns the number of bytes encoded and whether there's any errors along the way. If there is an error, the byte slice should be considered invalid.
type Pingresp ¶ added in v0.7.1
type Pingresp struct{}
A Pingresp packet is sent by the server to the client in response to a Pingreq. It indicates that the server is alive.
func NewPingresp ¶ added in v0.7.1
func NewPingresp() *Pingresp
NewPingresp creates a new Pingresp packet.
func (*Pingresp) Decode ¶ added in v0.7.1
Decode reads from the byte slice argument. It returns the total number of bytes decoded, and whether there have been any errors during the process.
func (*Pingresp) Encode ¶ added in v0.7.1
Encode writes the packet bytes into the byte slice from the argument. It returns the number of bytes encoded and whether there's any errors along the way. If there is an error, the byte slice should be considered invalid.
type Puback ¶ added in v0.7.1
type Puback struct {
// The packet identifier.
ID ID
}
A Puback packet is the response to a Publish packet with QOS level 1.
func (*Puback) Decode ¶ added in v0.7.1
Decode reads from the byte slice argument. It returns the total number of bytes decoded, and whether there have been any errors during the process.
func (*Puback) Encode ¶ added in v0.7.1
Encode writes the packet bytes into the byte slice from the argument. It returns the number of bytes encoded and whether there's any errors along the way. If there is an error, the byte slice should be considered invalid.
type Pubcomp ¶ added in v0.7.1
type Pubcomp struct {
// The packet identifier.
ID ID
}
A Pubcomp packet is the response to a Pubrel. It is the fourth and final packet of the QOS 2 protocol exchange.
func NewPubcomp ¶ added in v0.7.1
func NewPubcomp() *Pubcomp
NewPubcomp creates a new Pubcomp packet.
func (*Pubcomp) Decode ¶ added in v0.7.1
Decode reads from the byte slice argument. It returns the total number of bytes decoded, and whether there have been any errors during the process.
func (*Pubcomp) Encode ¶ added in v0.7.1
Encode writes the packet bytes into the byte slice from the argument. It returns the number of bytes encoded and whether there's any errors along the way. If there is an error, the byte slice should be considered invalid.
type Publish ¶ added in v0.7.1
type Publish struct {
// The message to publish.
Message Message
// If the Dup flag is set to false, it indicates that this is the first
// occasion that the client or server has attempted to send this
// Publish packet. If the dup flag is set to true, it indicates that this
// might be re-delivery of an earlier attempt to send the packet.
Dup bool
// The packet identifier.
ID ID
}
A Publish packet is sent from a client to a server or from server to a client to transport an application message.
func NewPublish ¶ added in v0.7.1
func NewPublish() *Publish
NewPublish creates a new Publish packet.
func (*Publish) Decode ¶ added in v0.7.1
Decode reads from the byte slice argument. It returns the total number of bytes decoded, and whether there have been any errors during the process.
func (*Publish) Encode ¶ added in v0.7.1
Encode writes the packet bytes into the byte slice from the argument. It returns the number of bytes encoded and whether there's any errors along the way. If there is an error, the byte slice should be considered invalid.
type Pubrec ¶ added in v0.7.1
type Pubrec struct {
// Shared packet identifier.
ID ID
}
A Pubrec packet is the response to a Publish packet with QOS 2. It is the second packet of the QOS 2 protocol exchange.
func (*Pubrec) Decode ¶ added in v0.7.1
Decode reads from the byte slice argument. It returns the total number of bytes decoded, and whether there have been any errors during the process.
func (*Pubrec) Encode ¶ added in v0.7.1
Encode writes the packet bytes into the byte slice from the argument. It returns the number of bytes encoded and whether there's any errors along the way. If there is an error, the byte slice should be considered invalid.
type Pubrel ¶ added in v0.7.1
type Pubrel struct {
// Shared packet identifier.
ID ID
}
A Pubrel packet is the response to a Pubrec packet. It is the third packet of the QOS 2 protocol exchange.
func (*Pubrel) Decode ¶ added in v0.7.1
Decode reads from the byte slice argument. It returns the total number of bytes decoded, and whether there have been any errors during the process.
func (*Pubrel) Encode ¶ added in v0.7.1
Encode writes the packet bytes into the byte slice from the argument. It returns the number of bytes encoded and whether there's any errors along the way. If there is an error, the byte slice should be considered invalid.
type QOS ¶ added in v0.10.0
type QOS byte
QOS is the type used to store quality of service levels.
const ( // QOSAtMostOnce defines that the message is delivered at most once, or it // may not be delivered at all. QOSAtMostOnce QOS = iota // QOSAtLeastOnce defines that the message is always delivered at least once. QOSAtLeastOnce QOS = iota // QOSExactlyOnce defines that the message is always delivered exactly once. QOSExactlyOnce QOS = iota // QOSFailure indicates that there has been an error while subscribing // to a specific topic. QOSFailure QOS = 0x80 )
func (QOS) Successful ¶ added in v0.10.0
Successful returns if the provided quality of service level represents a successful value.
type Suback ¶ added in v0.7.1
type Suback struct {
// The granted QOS levels for the requested subscriptions.
ReturnCodes []QOS
// The packet identifier.
ID ID
}
A Suback packet is sent by the server to the client to confirm receipt and processing of a Subscribe packet. The Suback packet contains a list of return codes, that specify the maximum QOS levels that have been granted.
func (*Suback) Decode ¶ added in v0.7.1
Decode reads from the byte slice argument. It returns the total number of bytes decoded, and whether there have been any errors during the process.
func (*Suback) Encode ¶ added in v0.7.1
Encode writes the packet bytes into the byte slice from the argument. It returns the number of bytes encoded and whether there's any errors along the way. If there is an error, the byte slice should be considered invalid.
type Subscribe ¶ added in v0.7.1
type Subscribe struct {
// The subscriptions.
Subscriptions []Subscription
// The packet identifier.
ID ID
}
A Subscribe packet is sent from the client to the server to create one or more Subscriptions. The server will forward application messages that match these subscriptions using PublishPackets.
func NewSubscribe ¶ added in v0.7.1
func NewSubscribe() *Subscribe
NewSubscribe creates a new Subscribe packet.
func (*Subscribe) Decode ¶ added in v0.7.1
Decode reads from the byte slice argument. It returns the total number of bytes decoded, and whether there have been any errors during the process.
func (*Subscribe) Encode ¶ added in v0.7.1
Encode writes the packet bytes into the byte slice from the argument. It returns the number of bytes encoded and whether there's any errors along the way. If there is an error, the byte slice should be considered invalid.
type Subscription ¶
type Subscription struct {
// The topic to subscribe.
Topic string
// The requested maximum QOS level.
QOS QOS
}
A Subscription is a single subscription in a Subscribe packet.
func (*Subscription) String ¶
func (s *Subscription) String() string
type Type ¶
type Type byte
Type represents the MQTT packet types.
const ( CONNECT Type CONNACK PUBLISH PUBACK PUBREC PUBREL PUBCOMP SUBSCRIBE SUBACK UNSUBSCRIBE UNSUBACK PINGREQ PINGRESP DISCONNECT )
All packet types.
func DetectPacket ¶
DetectPacket tries to detect the next packet in a buffer. It returns a length greater than zero if the packet has been detected as well as its Type.
type Unsuback ¶ added in v0.7.1
type Unsuback struct {
// Shared packet identifier.
ID ID
}
An Unsuback packet is sent by the server to the client to confirm receipt of an Unsubscribe packet.
func NewUnsuback ¶ added in v0.7.1
func NewUnsuback() *Unsuback
NewUnsuback creates a new Unsuback packet.
func (*Unsuback) Decode ¶ added in v0.7.1
Decode reads from the byte slice argument. It returns the total number of bytes decoded, and whether there have been any errors during the process.
func (*Unsuback) Encode ¶ added in v0.7.1
Encode writes the packet bytes into the byte slice from the argument. It returns the number of bytes encoded and whether there's any errors along the way. If there is an error, the byte slice should be considered invalid.
type Unsubscribe ¶ added in v0.7.1
type Unsubscribe struct {
// The topics to unsubscribe from.
Topics []string
// The packet identifier.
ID ID
}
An Unsubscribe packet is sent by the client to the server.
func NewUnsubscribe ¶ added in v0.7.1
func NewUnsubscribe() *Unsubscribe
NewUnsubscribe creates a new Unsubscribe packet.
func (*Unsubscribe) Decode ¶ added in v0.7.1
func (u *Unsubscribe) Decode(src []byte) (int, error)
Decode reads from the byte slice argument. It returns the total number of bytes decoded, and whether there have been any errors during the process.
func (*Unsubscribe) Encode ¶ added in v0.7.1
func (u *Unsubscribe) Encode(dst []byte) (int, error)
Encode writes the packet bytes into the byte slice from the argument. It returns the number of bytes encoded and whether there's any errors along the way. If there is an error, the byte slice should be considered invalid.
func (*Unsubscribe) Len ¶ added in v0.7.1
func (u *Unsubscribe) Len() int
Len returns the byte length of the encoded packet.
func (*Unsubscribe) String ¶ added in v0.7.1
func (u *Unsubscribe) String() string
String returns a string representation of the packet.
func (*Unsubscribe) Type ¶ added in v0.7.1
func (u *Unsubscribe) Type() Type
Type returns the packets type.
Source Files