Event API Reference#

The Event API is event subscribers based on TIP-28 Node Event API, it provides an easy way to subscribe node events via MQTT protocol.

Event Client Configuration#

struct event_client_config_t#

The event client configuration.

Public Members

char const *host#

The broker host url.

uint16_t port#

The broker port to connect with, usually it is 1883.

const char *client_id#

The client id to use, or NULL if a random client id should be generated.

uint8_t keepalive#

The number of seconds after which the broker should send a PING message to the client.

const char *username#

The username string, or NULL for no username authentication.

const char *password#

The password string, or NULL for an empty password.

Event IDs#

enum event_client_event_id_t#

Event IDs for handling IOTA Node events.

Values:

enumerator NODE_EVENT_ANY#
enumerator NODE_EVENT_ERROR#

on error event, additional context: connection return code

enumerator NODE_EVENT_CONNECTED#

connected to a node broker

enumerator NODE_EVENT_DISCONNECTED#

disconnected from the node broker

enumerator NODE_EVENT_SUBSCRIBED#

subscribed an event, additional context: msg_id

enumerator NODE_EVENT_UNSUBSCRIBED#

unsubscribed an event

enumerator NODE_EVENT_PUBLISHED#

published an event, additional context: msg_id

enumerator NODE_EVENT_DATA#

data event, additional context:

  • msg_id The message id

  • topic An pointer to the received topic

  • topic_len The length of the topic

  • data An pointer to the received data

  • data_len The length of the data for this event

  • retain The retain flag of the message

Initialize Event Service#

event_client_handle_t event_init(event_client_config_t *config)#

Initialize event service.

Parameters

  • config – [in] MQTT client config paramters

Register Event Callback Handler#

int event_register_cb(event_client_handle_t client, void (*callback)(event_client_event_t *event))#

Set the event callback handler.

Parameters

  • client – [in] The event client instance

  • callback – [in] An event callback handler

Subscribe To A Topic#

int event_subscribe(event_client_handle_t client, int *mid, char *topic, int qos)#

Subscribe an event.

Parameters

  • client – [in] The event client instance

  • mid – [out] If not NULL, mid will return the message id of the topic subscription

  • topic – [in] A node topic to subscribe

  • qos – [in] The QoS level for the topic

Returns

int 0 If Success

Unsubscribe To A Topic#

int event_unsubscribe(event_client_handle_t client, int *mid, char *topic)#

Unsubscribe an event.

Parameters

  • client – [in] The event client instance

  • mid – [out] If not NULL, mid will return the message id of the topic subscription

  • topic – [in] A node topic to subscribe

Returns

int 0 If Success

Start Event Service#

int event_start(event_client_handle_t client)#

Connect to Node broker with the given config.

Parameters

  • client – [in] The event client instance

Returns

int 0 If Success

Stop Event Service#

int event_stop(event_client_handle_t client)#

Disconnect from the Node broker.

Parameters

  • client – [in] The event client instance

Returns

int 0 If Success

Destroy Event Service#

int event_destroy(event_client_handle_t client)#

Stop and destroy event instance.

Parameters

  • client – [in] The event client instance

Returns

int 0 If Success

IOTA Event Topics#

milestone-info/latest#

Use TOPIC_MILESTONE_LATEST

event_subscribe(event_client_handle_t client, int *mid, TOPIC_MS_LATEST, int qos);

milestone-info/confirmed#

event_subscribe(event->client, NULL, TOPIC_MILESTONE_CONGIRMED, 1);

milestones#

TODO

blocks#

event_subscribe(event->client, NULL, TOPIC_BLOCKS, 1);

blocks/transaction#

event_subscribe(event->client, NULL, TOPIC_BLK_TRANSACTION, 1);

blocks/transaction/tagged-data#

TODO

blocks/transaction/tagged-data/{tag}#

TODO

blocks/tagged-data#

event_subscribe(event->client, NULL, TOPIC_BLK_TAGGED_DATA, 1);

blocks/tagged-data/{tag}#

TODO

transactions/{transaction ID}/included-block#

TODO

block-metadata/{block ID}#

TODO

block-metadata/referenced#

TODO

outputs/{Output ID}#

int event_sub_outputs_id(event_client_handle_t client, int *mid, char const output_id[], int qos)#

Subscribes outputs/{outputId} event.

Parameters

  • client – [in] The event client object

  • mid – [out] If not NULL, mid will return the message id of the topic subscription

  • output_id – [in] An output Id

  • qos – [in] The QoS level to be used with the topic

Returns

int 0 If success

outputs/nft/{NFT ID}#

int event_sub_outputs_nft_id(event_client_handle_t client, int *mid, char const nft_id[], int qos)#

Subscribes outputs/nfts/{nftId} event.

Parameters

  • client – [in] The event client object

  • mid – [out] If not NULL, mid will return the message id of the topic subscription

  • nft_id – [in] A nft id

  • qos – [in] The QoS level to be used with the topic

Returns

int 0 If success

outputs/aliases/{Alias ID}#

int event_sub_outputs_alias_id(event_client_handle_t client, int *mid, char const alias_id[], int qos)#

Subscribes outputs/aliases/{aliasId} event.

Parameters

  • client – [in] The event client object

  • mid – [out] If not NULL, mid will return the message id of the topic subscription

  • alias_id – [in] An alias id

  • qos – [in] The QoS level to be used with the topic

Returns

int 0 If success

outputs/foundries/{Foundry ID}#

int event_sub_outputs_foundry_id(event_client_handle_t client, int *mid, char const foundry_id[], int qos)#

Subscribes outputs/foundries/{foundryId} event.

Parameters

  • client – [in] The event client object

  • mid – [out] If not NULL, mid will return the message id of the topic subscription

  • foundry_id – [in] A foundry id

  • qos – [in] The QoS level to be used with the topic

Returns

int 0 If success

outputs/unlock/{condition}/{address}#

int event_sub_outputs_unlock_address(event_client_handle_t client, int *mid, char const *const unlock_condition, char const *const addr_bech32, int qos)#

Subscribes outputs/unlock/{condition}/{address} event.

Parameters

  • client – [in] The event client object

  • mid – [out] If not NULL, mid will return the message id of the topic subscription

  • unlock_condition – [in] Type of unlock condition of the output to look for. Allowed values: “address”, “storage-return”, “expiration”, “state-controller”, “governor”, “immutable-alias”, “+”

  • bech32_addr – [in] Bech32 encoded address

  • qos – [in] The QoS level to be used with the topic

Returns

int 0 If success

outputs/unlock/{condition}/{address}/spent#

int event_sub_outputs_unlock_address_spent(event_client_handle_t client, int *mid, char const *const unlock_condition, char const *const addr_bech32, int qos)#

Subscribes outputs/unlock/{condition}/{address}/spent event.

Parameters

  • client – [in] The event client object

  • mid – [out] If not NULL, mid will return the message id of the topic subscription

  • unlock_condition – [in] Type of unlock condition of the output to look for. Allowed values: “address”, “storage-return”, “expiration”, “state-controller”, “governor”, “immutable-alias”, “+”

  • bech32_addr – [in] Bech32 encoded address

  • qos – [in] The QoS level to be used with the topic

Returns

int 0 If success