packet

lib/message/doc.go

@@ -0,0 +1,141 @@
+// Copyright (c) 2014 The SurgeMQ Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/*
+Package message is an encoder/decoder library for MQTT 3.1 and 3.1.1 messages. You can
+find the MQTT specs at the following locations:
+
+	3.1.1 - http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/
+	3.1 - http://public.dhe.ibm.com/software/dw/webservices/ws-mqtt/mqtt-v3r1.html
+
+From the spec:
+
+	MQTT is a Client Server publish/subscribe messaging transport protocol. It is
+	light weight, open, simple, and designed so as to be easy to implement. These
+	characteristics make it ideal for use in many situations, including constrained
+	environments such as for communication in Machine to Machine (M2M) and Internet
+	of Things (IoT) contexts where a small code footprint is required and/or network
+	bandwidth is at a premium.
+
+	The MQTT protocol works by exchanging a series of MQTT messages in a defined way.
+	The protocol runs over TCP/IP, or over other network protocols that provide
+	ordered, lossless, bi-directional connections.
+
+
+There are two main items to take note in this package. The first is
+
+	type MessageType byte
+
+MessageType is the type representing the MQTT packet types. In the MQTT spec, MQTT
+control packet type is represented as a 4-bit unsigned value. MessageType receives
+several methods that returns string representations of the names and descriptions.
+
+Also, one of the methods is New(). It returns a new Message object based on the mtype
+parameter. For example:
+
+	m, err := CONNECT.New()
+	msg := m.(*ConnectMessage)
+
+This would return a PublishMessage struct, but mapped to the Message interface. You can
+then type assert it back to a *PublishMessage. Another way to create a new
+PublishMessage is to call
+
+	msg := NewConnectMessage()
+
+Every message type has a New function that returns a new message. The list of available
+message types are defined as constants below.
+
+As you may have noticed, the second important item is the Message interface. It defines
+several methods that are common to all messages, including Name(), Desc(), and Type().
+Most importantly, it also defines the Encode() and Decode() methods.
+
+	Encode() (io.Reader, int, error)
+	Decode(io.Reader) (int, error)
+
+Encode returns an io.Reader in which the encoded bytes can be read. The second return
+value is the number of bytes encoded, so the caller knows how many bytes there will be.
+If Encode returns an error, then the first two return values should be considered invalid.
+Any changes to the message after Encode() is called will invalidate the io.Reader.
+
+Decode reads from the io.Reader parameter until a full message is decoded, or when io.Reader
+returns EOF or error. The first return value is the number of bytes read from io.Reader.
+The second is error if Decode encounters any problems.
+
+With these in mind, we can now do:
+
+	// Create a new CONNECT message
+	msg := NewConnectMessage()
+
+	// Set the appropriate parameters
+	msg.SetWillQos(1)
+	msg.SetVersion(4)
+	msg.SetCleanSession(true)
+	msg.SetClientId([]byte("surgemq"))
+	msg.SetKeepAlive(10)
+	msg.SetWillTopic([]byte("will"))
+	msg.SetWillMessage([]byte("send me home"))
+	msg.SetUsername([]byte("surgemq"))
+	msg.SetPassword([]byte("verysecret"))
+
+	// Encode the message and get the io.Reader
+	r, n, err := msg.Encode()
+	if err == nil {
+		return err
+	}
+
+	// Write n bytes into the connection
+	m, err := io.CopyN(conn, r, int64(n))
+	if err != nil {
+		return err
+	}
+
+	fmt.Printf("Sent %d bytes of %s message", m, msg.Name())
+
+To receive a CONNECT message from a connection, we can do:
+
+	// Create a new CONNECT message
+	msg := NewConnectMessage()
+
+	// Decode the message by reading from conn
+	n, err := msg.Decode(conn)
+
+If you don't know what type of message is coming down the pipe, you can do something like this:
+
+	// Create a buffered IO reader for the connection
+	br := bufio.NewReader(conn)
+
+	// Peek at the first byte, which contains the message type
+	b, err := br.Peek(1)
+	if err != nil {
+		return err
+	}
+
+	// Extract the type from the first byte
+	t := MessageType(b[0] >> 4)
+
+	// Create a new message
+	msg, err := t.New()
+	if err != nil {
+		return err
+	}
+
+	// Decode it from the bufio.Reader
+	n, err := msg.Decode(br)
+	if err != nil {
+		return err
+	}
+
+
+*/
+package message