Events

This document provides a comprehensive guide on working with events in PrivMX, covering how to set up connections and event queues, listen for specific types of events like Thread or Store actions, and understand the structure of these events.

Working with Events

To start working with Events, you must:

Create connection to PrivMX Bridge instance.

auto connection = core::Connection::connect(PRIVATE_KEY,SOLUTION_ID,BRIDGE_URL);

Create Event Queue.

auto eventQueue = core::EventQueue::getInstance();

Start listening for events using waitEvent. EventQueue provides waitEvent method that blocks main browser's thread. To avoid freezing the entire app:

 // Map containing pairs of event type - list of callbacks
 std::shared_mutex callbacksMapMutex;
 std::map<std::string, std::function<void(std::shared_ptr<privmx::endpoint::core::Event>)>> callbacks; 
 std::atomic_bool listenForEventsPromise = true;
 // Start the EventQueue reading loop
 std::thread t([&](){
     while(listenForEventsPromise) {
         core::EventHolder event = eventQueue.waitEvent();
         std::shared_lock<std::shared_mutex> lock(callbacksMapMutex);
         auto search = callbacks.find(event.type);
         if (search != _map.end()) {
             search->second(event);
         }
     }
 });

Subscribe to channels.

    auto threadApi = thread::ThreadApi::create(connection);
    threadApi.subscribeForThreadEvents();

Add callback methods.
Add a list with callback methods that will be called on event with matching event type. In this example it's threadCreated:

 callbacks["threadCreated"] = [&](std::shared_ptr<privmx::endpoint::core::Event> event){std::cout << event.type << std::endl;};

Channels

Before receiving Events, your application must first subscribe to a group of events. Internally those groups are called "Channels".

Channels can be divided into two types:

Container related: Those channels notify about changes related to a given Container type. After subscribing to these channels, you will receive events when someone creates, updates, or deletes a Container with matching type in your Solution.
Item related: Those channels are related to a specific Container. When subscribed, you will receive events related to item changes in a given Container.

PrivMX Endpoint provides subscribing methods for each Container.

Types of Events

Every change in PrivMX corresponds to a specific event type. Event names follow common schema:

Example Container events:

Created - triggers when a new Container is created in your Context
Deleted - triggers when a Container is deleted from your Context
Updated - triggers when a Container is updated in your Context
Stats Changed - triggers when a Container is updated in your Context

Example Item events:

Created - triggers when an item is sent to a Container
Deleted - triggers when an item is deleted from a Container
Updated - triggers when an item is deleted from a Container

Examples

Inboxes have an inboxEntryCreated event triggered when an entry is sent to an Inbox.
Stores have a storeCreated event triggered when new Store is created in Context.

PrivMX Endpoint provides methods in each Container's API for subscribing to these channels. You can refer to platform-specific documentation on how to subscribe for necessary channels.

Structure

The main strength of events is that they contain data related to the occurred changes. Each Event related to a Container has the following format:

Field	Type	Description
channel	`string`	Name of channel related to this event
connectionId	`string`	ID of one of your current connections
type	`string`	Type of received event e.g., `"storeCreated"` or `"threadNewMessage"`
data	`T`	`T` depends on `type` of event and contains new/updated data

Because events are triggered after every change, you don't have to constantly refetch all data. A good practice is to fetch data on initial user entry and only modify your existing data based on received event.

Next Steps

For more details, refer to each Container's specific documentation: