README

SYNOPSIS

      use AnyEvent::MQTT;
      my $mqtt = AnyEvent::MQTT->new;
      my $cv = $mqtt->subscribe(topic => '/topic',
                                callback => sub {
                                     my ($topic, $message) = @_;
                                     print $topic, ' ', $message, "\n"
                                   });
      my $qos = $cv->recv; # subscribed, negotiated QoS == $qos
    
      # publish a simple message
      $cv = $mqtt->publish(message => 'simple message',
                              topic => '/topic');
      $cv->recv; # sent
    
      # publish line-by-line from file handle
      $cv =  $mqtt->publish(handle => \*STDIN,
                            topic => '/topic');
      $cv->recv; # sent
    
      # publish from AnyEvent::Handle
      $cv = $mqtt->publish(handle => AnyEvent::Handle->new(my %handle_args),
                           topic => '/topic');
      $cv->recv; # sent

DESCRIPTION

    AnyEvent module for MQTT client.

    IMPORTANT: This is an early release and the API is still subject to
    change.

DISCLAIMER

    This is not official IBM code. I work for IBM but I'm writing this in
    my spare time (with permission) for fun.

    Constructs a new AnyEvent::MQTT object. The supported parameters are:

    host

      The server host. Defaults to 127.0.0.1.

    port

      The server port. Defaults to 1883.

    timeout

      The timeout for responses from the server.

    keep_alive_timer

      The keep alive timer.

    user_name

      The user name for the MQTT broker.

    password

      The password for the MQTT broker.

    tls

      Set flag to enable TLS encryption, Default is no encryption.

    will_topic

      Set topic for will message. Default is undef which means no will
      message will be configured.

    will_qos

      Set QoS for will message. Default is 'at-most-once'.

    will_retain

      Set retain flag for will message. Default is 0.

    will_message

      Set message for will message. Default is the empty message.

    clean_session

      Set clean session flag for connect message. Default is 1.

    client_id

      Sets the client id for the client overriding the default which is
      NetMQTTpmNNNNN where NNNNN is the current process id.

    message_log_callback

      Defines a callback to call on every message.

    on_error

      Defines a callback to call when some error occurs.

      Two parameters are passed to the callback.

          $on_error->($fatal, $message)

      where $fatal is a boolean flag and $message is the error message. If
      the error is fatal, $fatal is true.

    handle_args

        a reference to a list to pass as arguments to the
        L<AnyEvent::Handle> constructor (defaults to
        an empty list reference).

    This method attempts to destroy any resources in the event of a
    disconnection or fatal error.

    This method is used to publish to a given topic. It returns an AnyEvent
    condvar which is notified when the publish is complete (written to the
    kernel or ack'd depending on the QoS level). The parameter hash must
    included at least a topic value and one of:

    message

        with a string value which is published to the topic,

    handle

       the value of which must either be an L<AnyEvent::Handle> or will be
       passed to an L<AnyEvent::Handle> constructor as the C<fh> argument.
       The L<push_read()> method is called on the L<AnyEvent::Handle> with a
       callback that will publish each chunk read to the topic.

    The parameter hash may also keys for:

    qos

        to set the QoS level for published messages (default
        MQTT_QOS_AT_MOST_ONCE),

    handle_args

        a reference to a list to pass as arguments to the
        L<AnyEvent::Handle> constructor in the final case above (defaults to
        an empty list reference), or

    push_read_args

        a reference to a list to pass as the arguments to the
        L<AnyEvent::Handle#push_read> method (defaults to ['line'] to read,
        and subsequently publish, a line at a time.

    Returns a 16-bit number to use as the next message id in a message
    requiring an acknowledgement.

    This method subscribes to the given topic. The parameter hash may
    contain values for the following keys:

    topic

        for the topic to subscribe to (this is required),

    callback

        for the callback to call with messages (this is required),

    qos

        QoS level to use (default is MQTT_QOS_AT_MOST_ONCE),

    cv

        L<AnyEvent> condvar to use to signal the subscription is complete.
        The received value will be the negotiated QoS level.

    This method returns the value of the cv parameter if it was supplied or
    an AnyEvent condvar created for this purpose.

    This method unsubscribes to the given topic. The parameter hash may
    contain values for the following keys:

    topic

        for the topic to unsubscribe from (this is required),

    callback

        for the callback to call with messages (this is optional and currently
        not supported - all callbacks are unsubscribed),

    cv

        L<AnyEvent> condvar to use to signal the unsubscription is complete.

    This method returns the value of the cv parameter if it was supplied or
    an AnyEvent condvar created for this purpose.

    This method starts the connection to the server. It will be called
    lazily when required publish or subscribe so generally is should not be
    necessary to call it directly.

    This method is used to register an AnyEvent::Handle read type method to
    read MQTT messages.

POD ERRORS

    Hey! The above document had some coding errors, which are explained
    below:

    Around line 39:

      Unknown directive: =method

    Around line 123:

      Unknown directive: =method

    Around line 128:

      Unknown directive: =method

    Around line 174:

      Unknown directive: =method

    Around line 179:

      Unknown directive: =method

    Around line 208:

      Unknown directive: =method

    Around line 233:

      Unknown directive: =method

    Around line 239:

      Unknown directive: =method