Events

Events are handled as flows in Kotlin and can be retrieved from the agent.

The examples of event flows below do not include the code needed to launch them in a background coroutine scope. You must add that code in your Kotlin code to take the handlers off of the main thread.

Kotlin

val didExchangeEvents? = agent.events.getEventBus(DidExchangeEvents::class)
// or
val didExchangeEvents = agent.events.getDidExchangeEvents()?: throw Error("Events not initialized by agent")

The getEventBus function will attempt to retrieve the event bus class passed to it. This exists because custom event flows can be registered and stored in the agent.events eventManager object.

There are eight base flows for different actions that the Agent manages. Their functions are:

getDidExchangeEvents()
getAgentEvents()
getCredentialEvents
getEventBusEvents()
getMessageEvents()
getProofEvents()
getTrustPingEvents()
getWebsocketEvents()

All of the listed functions exist on the events property of the agent. The event bus events pertain to record updates. The message events pertain to all incoming messages regardless of type. Agent events are emitted to indicate the state (Start, Running, Stop) of the Agent.

Both the named functions and the getEventBus may return null if, for some reason, the event bus has not yet been registered to the agent's eventManager. The only way the named function would return null is if the Agent initializes with errors.

Once you have the events you can perform operations on them to filter for certain IDs or states in order to complete processes or inform the user when things are occurring.

Performing certain actions that wait for completion of a protocol inside of an event handler can cause a deadlock situation. It is not advised to wait for protocol completion inside a continuous event handler.

Example of what NOT to do:

BAD example (Kotlin)

// Example of what NOT to do
val didExchangeEvents = agent.events.getDidExchangeEvents()?: throw Error("Events not initialized by agent")

didExchangeEvents.events.onEach{
    // Causes deadlock because requestConnection will not return until the response message is processed
    // This can be avoided by calling this function in a separate thread 
    agent.didExchange.requestConnection(it.didExchangeRecord.id, it.outOfBandRecord.id)
}.collect()

// Auto accept should be used instead of trying to do this. This is an intentionally BAD example

If you need to wait for the agent to complete an action, you should wait for a specific event/state instead:

Kotlin

val didExchangeEvents = agent.events.getDidExchangeEvents()?: throw Error("Events not initialized by agent")
// Waits for the first didExchangeStateChangedEvent to be emitted that is in the completed state
didExchangeEvents.events.first{
   it.didExchangeRecord.state == DidExchangeState.Completed
}
// Additional attributes (such as ID) on the record can be used to wait for a specific record to reach a certain state

In Kotlin the events use flows; this allows the use of the Flow API on all events.

Swift uses KMPNativeCoroutines (https://github.com/rickclephas/KMP-NativeCoroutines) (1.0.0-ALPHA-23) as a dependency that allows the Kotlin flows to be turned into native Swift observables, AsyncSequence, and potentially more.

Swift

// Turns the didExchangeEvents into a swift asyncSequence
let credentialEvents = asyncSequence(for: agent.events.getCredentialEvents()!.events)

Events are also wrapped with convenience methods so you can easily listen to events without a third party library or when using Objective-C:

onDidExchangeStateChanged
onCredentialStateChanged
onTrustPingEvent
onAgentEvent
onRecordEvent
onProofEvent
onWebsocketEvent

Objective-C example:

Objective-C

void (^removeListener)(ProvenmobileKotlinCancellationException * _Nullable) =  
   [agent.events onDidExchangeStateChangedCallback:^(
      ProvenmobileDidExchangeStateChangedEvent *_Nonnull event
   ) {
      // Handle DidExchangeStateChangedEvent here
   }

// Remove listener when no longer needed
removeListener(nil);

Swift example:

Swift

let removeListener = agent.events.onDidExchangeStateChanged { event in
   // Handle DidExchangeStateChangedEvent here
}
// Remove listener when no longer needed
removeListener(nil)

Events in React Native are handled differently than in Kotlin and Swift. The format of events on the Agent is similar but is done in a simpler manner.

Instead of getting an events object, you register a handler function that will be called on all events of the specified type the handler is registered to.

TypeScript

// Registers a handler that is called on all Did Exchange events
const didExchangeRemove = agent.events.registerDidExchangeHandler(
    event => {
      if (event.didExchangeRecord.state === DidExchangeState.COMPLETED) {
        console.log(
          'didExchange completed',
          event.didExchangeRecord.theirLabel,
        )
      }
    })

// Unregister the handler when no longer needed
didExchangeRemove()

The return of registering a handler is a function that will remove or unregister the handler. Calling the removal function will stop the given handler from being called on any future events.

Note: Registered events will not persist after the app has been closed.

PreviousAgent NextiOS Async

Last updated 25 days ago

Was this helpful?