Messaging

The Messaging API enables containers to communicate through a publish-subscribe pattern, allowing for decoupled, asynchronous interactions without direct dependencies.

---

Header File

To use the Messaging API in your application, include the ocre_api.h header from the Atym Toolchain, and link the ocre-sdk library when building your application.

#include "ocre_api.h"

Container Permissions

When using the messaging API in your application, make sure to include the messaging permission in your build.yaml configuration file. This enables build-time validation to ensure your application only uses the messaging functions you've declared.

config:
  permissions:
    - messaging

---

Execution Environment

Container applications shall use ocre_process_events() function to process their messaging events. This is usually done in a loop, similar to following:

    // Main event loop - process events continuously
    while (1) {
        ocre_process_events();
    }

---

Types

Message Structure

A structure defining the message format.

typedef struct ocre_msg {
    uint32_t mid;         ///< Message ID - auto-incremented for each message
    char *topic;          ///< Topic name for the message
    char *content_type;   ///< Content type of the message (MIME type recommended)
    void *payload;        ///< Pointer to the message payload
    uint32_t payload_len; ///< Length of the payload in bytes
} ocre_msg_t;

---

Methods

Initialize Messaging System

Initializes the messaging system by setting up a message queue and starting a subscriber thread. If already initialized, the function logs a warning but proceeds without error.

void ocre_msg_system_init(void);

Returns:

• None

Publish Message

Publishes a message to the specified topic.

int ocre_publish_message(const char *topic, const char *content_type, const void *payload, uint32_t payload_len);

Fails if the messaging system is not initialized, if topic, content_type, or payload is NULL/empty, if payload_len is 0, or if the message queue is full.

Parameters:

Name	Type	Description
topic	const char	Topic name to publish the message to
content_type	const char	Content type of the message (MIME type recommended)
payload	const void	Pointer to the message payload buffer
payload_len	uint32_t	Length of the payload in bytes

Returns:

Value	Description
0	Message published successfully
-1	Failed to publish message (see error codes)

Subscribe to Topic

Subscribes to a topic to receive messages.

int ocre_subscribe_message(const char *topic);

Parameters:

Name	Type	Description
topic	const char	Topic name to subscribe to

Returns:

Value	Description
0	Subscription successful
-1	Failed to subscribe (see error codes)

Free Messaging Event Data

Frees allocated memory for a messaging event in the WASM module. This function releases the allocated memory for the topic, content-type, and payload associated with a messaging event received by the WASM module. It should be called after processing the message in ocre_process_events() to prevent memory leaks.

int ocre_messaging_free_module_event_data(uint32_t topic_offset, uint32_t content_offset, uint32_t payload_offset);

Parameters:

Name	Type	Description
topic_offset	uint32_t	Offset in WASM memory for the message topic
content_offset	uint32_t	Offset in WASM memory for the message content-type
payload_offset	uint32_t	Offset in WASM memory for the message payload

Returns:

Value	Description
0	Memory freed successfully
negative value	Error code

---

Reference

Function	Description	Parameters	Return Value	Error Conditions
ocre_msg_system_init	Initializes the messaging system	None	None	None
ocre_publish_message	Publishes a message to a topic	topic: Topic name content_type: MIME type payload: Message content payload_len: Content length	0: Success -1: Failure	Topic is NULL/empty Content type is NULL/empty Payload is NULL or length is 0 Message queue is full
ocre_subscribe_message	Subscribes to messages on a topic	topic: Topic name	0: Success -1: Failure	Topic is NULL/empty Subscription limit reached
ocre_messaging_free_module_event_data	Frees message event memory	topic_offset: Topic memory offset content_offset: Content-type memory offset payload_offset: Payload memory offset	0: Success Negative: Error	Invalid memory offsets