okiffsdk

package module
v1.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 13, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

README

okiff-sdk-go

Go SDK for connecting to and communicating over MQTT brokers. Built as a precompiled static library with CGo bindings for performance and ease of deployment.


Requirements

  • Go 1.21 or later
  • Linux x86-64
  • GCC / G++ (CGo build toolchain)
  • libpaho-mqtt3c installed system-wide

Install on Debian/Ubuntu:

sudo apt install libpaho-mqtt3c-dev

Install on Manjaro/Arch:

sudo pacman -S paho-mqtt-c

Installation

go get github.com/okiffms/okiff-sdk

Quick Start

package main

import (
    "fmt"
    "time"

    okiffsdk "github.com/okiffms/okiff-sdk"
)

func main() {
    sdk := okiffsdk.New()
    defer sdk.Destroy()

    // Callbacks
    sdk.OnConnection(func(connected bool, rc int) {
        fmt.Printf("[onConnection] connected=%v rc=%d\n", connected, rc)
    })

    sdk.OnMessage(func(topic, payload string) {
        fmt.Printf("[onMessage] topic=%s payload=%s\n", topic, payload)
    })

    // Initialize and connect
    if err := sdk.Init(
        "my_client",
        "broker.example.com:1883",
        "tcp",
        "username",
        "password",
    ); err != nil {
        fmt.Println("Init error:", err)
        return
    }

    ok := sdk.Connect()
    fmt.Println("Connect() =>", ok)

    if ok {
        sdk.Subscribe("my/topic", 0)
        time.AfterFunc(500*time.Millisecond, func() {
            sdk.Publish("my/topic", "hello", 0, false)
        })
    }

    // Cleanup
    time.Sleep(5 * time.Second)
    sdk.Disconnect()
    sdk.Stop()
}

API Reference

New() *SDK

Allocates and returns a new SDK instance.


Init(clientId, brokerHost, protocol, username, password string) error

Initializes the SDK. Must be called before Connect.

Parameter Type Description
clientId string Unique identifier for this client
brokerHost string Broker address including port, e.g. broker.example.com:1883
protocol string Transport protocol: "tcp" or "ssl"
username string Authentication username
password string Authentication password

Returns: error if the internal client cannot be created, nil on success.


Connect() bool

Connects to the broker.

Returns: true on success, false on failure.


Disconnect()

Gracefully disconnects from the broker.


Publish(topic, payload string, qos int, retained bool)

Publishes a message to a topic.

Parameter Type Default Description
topic string required MQTT topic string
payload string required Message body
qos int 0 Quality of Service: 0, 1, or 2
retained bool false Whether the broker retains the message

Subscribe(topic string, qos int) bool

Subscribes to a topic.

Parameter Type Description
topic string MQTT topic. Wildcards: + (single level), # (multi-level)
qos int Maximum QoS level for received messages

Returns: true on success, false on failure.


Unsubscribe(topic string)

Removes a topic subscription.

Parameter Type Description
topic string Exact topic string used in Subscribe

OnMessage(handler func(topic, payload string))

Registers a callback invoked when a message arrives on any subscribed topic.

sdk.OnMessage(func(topic, payload string) {
    // topic   — topic on which the message was received
    // payload — message body
})

OnConnection(handler func(connected bool, rc int))

Registers a callback invoked on every connection state change.

sdk.OnConnection(func(connected bool, rc int) {
    // connected — true = connected, false = disconnected or lost
    // rc        — 0 = clean disconnect, -1 = unexpected loss
})
Event connected rc
Connect() succeeds true 0
Disconnect() called false 0
Broker drops connection false -1

IsConnected() bool

Returns the current connection state.


Stop()

Stops all activity and releases all resources. Must be called after Disconnect.


Destroy()

Frees the SDK handle. Must be called after Stop. Use with defer.


License

Proprietary — all rights reserved.

Documentation

Overview

Package okiffsdk provides Go bindings for the Okiff MQTT SDK. It wraps a prebuilt static library (libokiff_sdk.a) via CGo.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ConnectionHandler

type ConnectionHandler func(connected bool, rc int)

ConnectionHandler is called on every connection state change. connected: true = connected, false = disconnected or lost. rc: 0 = clean disconnect, -1 = unexpected loss.

type MessageHandler

type MessageHandler func(topic, payload string)

MessageHandler is called when a message arrives on a subscribed topic.

type SDK

type SDK struct {
	// contains filtered or unexported fields
}

SDK is the main client handle. Create one with New().

func New

func New() *SDK

New allocates and returns a new SDK instance.

func (*SDK) Connect

func (s *SDK) Connect() bool

Connect establishes the connection to the broker. Returns true on success, false on failure.

func (*SDK) Destroy

func (s *SDK) Destroy()

Destroy frees the SDK handle. Call after Stop.

func (*SDK) Disconnect

func (s *SDK) Disconnect()

Disconnect gracefully disconnects from the broker.

func (*SDK) Init

func (s *SDK) Init(clientId, brokerHost, protocol, username, password string) error

Init initializes the MQTT client. Must be called before Connect.

func (*SDK) IsConnected

func (s *SDK) IsConnected() bool

IsConnected returns the current connection state.

func (*SDK) OnConnection

func (s *SDK) OnConnection(h ConnectionHandler)

OnConnection registers a callback invoked on every connection state change. Replaces any previously registered handler.

func (*SDK) OnMessage

func (s *SDK) OnMessage(h MessageHandler)

OnMessage registers a callback invoked when a message arrives on any subscribed topic. Replaces any previously registered handler.

func (*SDK) Publish

func (s *SDK) Publish(topic, payload string, qos int, retained bool)

Publish sends a message to a topic. qos: 0 = at most once, 1 = at least once, 2 = exactly once. retained: broker stores the message for future new subscribers.

func (*SDK) Stop

func (s *SDK) Stop()

Stop stops all activity and releases all resources. Must be called as the final cleanup step, after Disconnect.

func (*SDK) Subscribe

func (s *SDK) Subscribe(topic string, qos int) bool

Subscribe registers a subscription on the given topic. Returns true on success, false on failure.

func (*SDK) Unsubscribe

func (s *SDK) Unsubscribe(topic string)

Unsubscribe removes a topic subscription.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL