NAME

       libmosquitto - MQTT version 3.1 client library

DESCRIPTION

       This is an overview of how to use libmosquitto to create MQTT aware client programs. There
       may be separate man pages on each of the functions described here in the future. There are
       also bindings for libmosquitto for C++ and Python. They are not documented here.

       This  is  fairly  incomplete,  please  see  mosquitto.h  for  a  better description of the
       functions.

STATUS

       The libmosquitto api is currently regarded as experimental and unstable and may change  in
       future releases.

LIBMOSQUITTO SYMBOL NAMES

       All  public  functions  in  libmosquitto have the prefix "mosquitto_". Any other functions
       defined in the source code are to be treated as private functions and may  change  between
       any release. Do not use these functions!

FUNCTIONS

   LIBRARY VERSION
       unsigned long mosquitto_lib_version (int *major, int *minor, int *revision);

       Obtain  version  information about the library. If any of major, minor or revision are not
       NULL they will return the corresponding version numbers. The return value  is  an  integer
       representation  of  the  complete  version number (e.g. 9000 for 0.9) that can be used for
       comparisons.

   LIBRARY INITIALISATION AND CLEANUP
       int mosquitto_lib_init (void);
       int mosquitto_lib_cleanup (void);

   CLIENT CONSTRUCTOR/DESTRUCTOR
       struct mosquitto *mosquitto_new (const char *id, void *obj);
       void mosquitto_destroy (struct mosquitto *mosq);

   LOGGING
       int mosquitto_log_init (struct mosquitto *mosq, int priorities, int destinations);

       Configure the logging settings for this client. Returns 0 on success, 1 on error.

       Set priorities by ORing any of the items in the following list:

       • MOSQ_LOG_INFO

       • MOSQ_LOG_NOTICE

       • MOSQ_LOG_WARNING

       • MOSQ_LOG_ERROR

       • MOSQ_LOG_DEBUG

       Set destinations by ORing any of the items in the following list:

       • MOSQ_LOG_NONE

       • MOSQ_LOG_STDOUT

       • MOSQ_LOG_STDERR

   WILLS
       int mosquitto_will_set (struct mosquitto *mosq, bool will, const char *topic, uint32_t
                              payloadlen, const uint8_t *payload, int qos, bool retain);

   CONNECT/DISCONNECT
       void mosquitto_connect (struct mosquitto *mosq, const char *host, int port, int keepalive,
                              bool clean_session);
       void mosquitto_reconnect (struct mosquitto *mosq);
       int mosquitto_disconnect (struct mosquitto *mosq);

   PUBLISH
       int mosquitto_publish (struct mosquitto *mosq, uint16_t *mid, const char *topic, uint32_t
                             payloadlen, const uint8_t *payload, int qos, bool retain);

   SUBSCRIBE/UNSUBSCRIBE
       int mosquitto_subscribe (struct mosquitto *mosq, uint16_t *mid, const char *sub, int qos);
       int mosquitto_unsubscribe (struct mosquitto *mosq, uint16_t *mid, const char *sub);

   NETWORK LOOP
       int mosquitto_loop (struct mosquitto *mosq, int timeout);
       int mosquitto_loop_read (struct mosquitto *mosq);
       int mosquitto_loop_write (struct mosquitto *mosq);
       int mosquitto_loop_misc (struct mosquitto *mosq);
       int mosquitto_socket (struct mosquitto *mosq);

   CALLBACKS
       See mosquitto.h

EXAMPLES

       #include <mosquitto.h>

       void my_message_callback(void *obj, struct mosquitto_message *message)
       {
            if(message->payloadlen){
                 printf("%s %s\n", message->topic, message->payload);
            }else{
                 printf("%s (null)\n", message->topic);
            }
            fflush(stdout);
       }

       void my_connect_callback(void *obj, int result)
       {
            struct mosquitto *mosq = obj;

            int i;
            if(!result){
                 mosquitto_subscribe(mosq, topics[i], topic_qos);
            }else{
                 fprintf(stderr, "Connect failed\n");
            }
       }

       void my_subscribe_callback(void *obj, uint16_t mid, int qos_count, const uint8_t *granted_qos)
       {
            int i;

            printf("Subscribed (mid: %d): %d", mid, granted_qos[0]);
            for(i=1; i<qos_count; i++){
                 printf(", %d", granted_qos[i]);
            }
            printf("\n");
       }

       int main(int argc, char *argv[])
       {
            char id[30];
            int i;
            char *host = "localhost";
            int port = 1883;
            int keepalive = 60;
            bool clean_session = true;
            struct mosquitto *mosq = NULL;

            mosq = mosquitto_new(id, NULL);
            if(!mosq){
                 fprintf(stderr, "Error: Out of memory.\n");
                 return 1;
            }
            mosquitto_log_init(mosq, MOSQ_LOG_DEBUG | MOSQ_LOG_ERR | MOSQ_LOG_WARNING
                      | MOSQ_LOG_NOTICE | MOSQ_LOG_INFO, MOSQ_LOG_STDERR);

            mosquitto_connect_callback_set(mosq, my_connect_callback);
            mosquitto_message_callback_set(mosq, my_message_callback);
            mosquitto_subscribe_callback_set(mosq, my_subscribe_callback);

            if(mosquitto_connect(mosq, host, port, keepalive, clean_session)){
                 fprintf(stderr, "Unable to connect.\n");
                 return 1;
            }

            while(!mosquitto_loop(mosq, -1)){
            }
            mosquitto_destroy(mosq);
            return 0;
       }

SEE ALSO

       mosquitto(8) mqtt(7)

AUTHOR

       Roger Light <roger@atchoo.org>

                                         5 February 2012                          libmosquitto(3)