Event API Reference#

The Event API is event subscribers based on RFC: 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 Node Events#

Confirmed Milestones#

struct milestone_confirmed_t#

Stores timestamp and index.

Public Members

uint64_t timestamp#

The timestamp of confirmed milestone.

uint32_t index#

The index of confirmed milestone.

Parse Confirmed Milestone JSON response#

int parse_milestones_confirmed(char *data, milestone_confirmed_t *res)#

Parse milestone confirmed response object.

Parameters

  • data – [in] Response data to parse

  • res – [out] Parsed response object

Returns

int 0 If success

The Latest Milestone#

struct milestone_latest_t#

Stores timestamp and index.

Public Members

uint64_t timestamp#

The timestamp of latest milestone.

uint32_t index#

The index of latest milestone.

Parse Confirmed Milestone JSON response#

int parse_milestone_latest(char *data, milestone_latest_t *res)#

Parse milestone latest response.

Parameters

  • data – [in] Response data to parse

  • res – [out] Parsed response object

Returns

int 0 If success

The Message Metadata#

struct msg_metadata_t#

Stores the message metadata response object.

Public Members

char msg_id[IOTA_MESSAGE_ID_HEX_BYTES + 1]#

The hex encoded message ID string.

UT_array *parents#

The parent message IDs.

char inclusion_state[32]#

The ledger inclusion state of the transaction payload, one of noTransaction, conflicting or included

bool is_solid#

Whether the message is solid.

bool should_promote#

Whether the message should be promoted, optional.

bool should_reattach#

Whether the message should be reattached, optional.

uint64_t referenced_milestone#

The milestone index that references the message, optional.

Subscribe for messages/{messageid}/metadata event#

int event_subscribe_msg_metadata(event_client_handle_t client, int *mid, char const msg_id[], int qos)#

Subscribes messages/{messageid}/metadata event.

Parameters

  • client – [in] The event client instance

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

  • msg_id – [in] A messsage id for the event

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

Returns

int 0 If Success

Allocate a message metadata onject#

msg_metadata_t *res_msg_metadata_new(void)#

Allocates a message metadata onject.

Returns

msg_metadata_t*

Free a message metadata object#

void res_msg_metadata_free(msg_metadata_t *res)#

Free a message metadata object.

Parameters

  • res – [in] A message metadata object

Parse a message metadata response#

int parse_messages_metadata(char *data, msg_metadata_t *res)#

Parse a message metadata response.

Parameters

  • data – [in] The response data to be parsed

  • res – [out] The message metadata object

Returns

int 0 If success

Get the count of parent message ids#

size_t res_msg_metadata_parents_count(msg_metadata_t *res)#

Gets the count of parent message ids.

Parameters

  • res – [in] The message metadata object

Returns

size_t The count of parent message ids

Get a parent message ID by index#

char *res_msg_metadata_parent_get(msg_metadata_t *res, size_t index)#

Gets the parent message ID by a given index.

Parameters

  • res – [in] The message metadata object

  • index – [in] An index

Returns

char* The parent message ID string

The Output Payloads#

struct event_outputs_payload_t#

The structure for outputs payload response.

Public Members

char msg_id[API_MSG_ID_HEX_STR_LEN]#

The hex encoded message ID of the message.

char tx_id[API_TX_ID_HEX_STR_LEN]#

The hex encoded transaction id from which this output originated.

uint16_t output_index#

The index of the output.

bool is_spent#

Whether this output is spent.

uint64_t ledger_index#

The ledger(milestone) index at which this output was available at.

event_output_t output#

The output object with output type, amount and address.

struct event_output_t#

The output object of the response.

Public Members

uint32_t output_type#

The output type.

uint64_t amount#

The amount of the output.

char addr[65]#

A hex string of the ed25519 address.

Subscribe for addresses/{address}/outputs event#

int event_sub_address_outputs(event_client_handle_t client, int *mid, char const addr[], bool is_bech32, int qos)#

Subscribes addresses/{address}/outputs event.

Parameters

  • client – [in] The event client object

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

  • addr – [in] An address string

  • is_bech32 – [in] The address type, true: Bech32 address, false: ed25519 address

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

Returns

int 0 If success

Subscribe for outputs/{outputId} event#

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

Parse the outputs payload#

int event_parse_outputs_payload(char const data[], event_outputs_payload_t *res)#

Parse the outputs payload.

Parameters

  • data – [in] The string data of the response

  • res – [out] The output payload object

Returns

int 0 If success

The Serialized Outputs#

Subscribe for transactions/{transactionId}/included_message event#

int event_sub_txn_included_msg(event_client_handle_t client, int *mid, char const transaction_id[], int qos)#

Subscribes transactions/{transactionId}/included_message topic.

Parameters

  • client – [in] The event client object

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

  • transaction_id – [in] A transacton id

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

Returns

int 0 If success

Subscribe for messages/indexation/{index} event#

int event_sub_msg_indexation(event_client_handle_t client, int *mid, char const index[], int qos)#

Subscribes messages/indexation/{index} topic for receiving messages with indexation payloads.

Parameters

  • client – [in] The event client object

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

  • index – [in] An index to get messages

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

Returns

int 0 If success