mqtt/api.yaml at master · j-forster/mqtt · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
name: MQTT
tags: [ Networking ]
version: 0.0.9
doc: "
  This repo is a implementation of the [MQTT Protocol](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html)
  for the [Go Programming Language](https://golang.org/).

  [![GoDoc](https://godoc.org/github.com/j-forster/mqtt?status.svg)](https://godoc.org/github.com/j-forster/mqtt)

  ## What is MQTT?

  ```
  MQTT stands for MQ Telemetry Transport. It is a publish/subscribe, extremely
  simple and lightweight messaging protocol, designed for constrained devices
  and low-bandwidth, high-latency or unreliable networks. The design principles
  are to minimise network bandwidth and device resource requirements whilst also
  attempting to ensure reliability and some degree of assurance of delivery.
  These principles also turn out to make the protocol ideal of the emerging
  “machine-to-machine” (M2M) or “Internet of Things” world of connected devices,
  and for mobile applications where bandwidth and battery power are at a premium.
  ```

  → See [MQTT FAQ](http://mqtt.org/faq)"

symbols:
  - name: ListenAndServer
    doc: Start a new mqtt server at the given address.
    params:
      - name: addr
        type: string
      - name: handler
        type: ./Handler
    returns: []

  - name: Handler
    doc: A plugin handler for advanced server functionality.
    symbols:
      - name: Connect
        doc: Called on every new connection. Return an error to reject the mqtt client.
        params:
          - name: ctx
            type: .\Context
          - name: username
            type: string
          - name: password
            type: string
        returns:
          - name: err
            type: error
      - name: Disconnect
        doc: Called when the mqtt client disconnects.
        params:
          - name: ctx
            type: .\Context
        returns: []
      - name: Publish
        doc: Called when a mqtt client publishs a message. Return an error to stop this message from being published.
        params:
          - name: ctx
            type: .\Context
          - name: msg
            type: .\Message
        returns:
          - name: err
            type: error
      - name: Subscribe
        doc: Called when a mqtt client subscribes to a topic. Return an error to cancel this subscription.
        params:
          - name: ctx
            type: .\Context
          - name: topic
            type: string
          - name: qos
            doc: Quality of Service
            type: byte
        returns:
          - name: err
            type: error

  - name: Context
    doc: A wrapper for mqtt connections.
    symbols:
      - name: ClientID
        doc: MQTT Client ID
        type: string
      - name: Will
        doc: Will message, if any.
        type: Pointer<./Message>

  - name: Message
    symbols:
      - name: topic
        type: string
      - name: buffer
        type: Slice<byte>
      - name: qos
        type: byte