Device Messenger Subsystem

note

Added in v3.2.0

Device Messenger shares the lifetime of its owning device, meaning it is created when a device is created and is guaranteed to exist within that device until it shutdown. Each device in world will have it's own unique messenger. Although device messenger is similar to Global Messenger Subsystem they both are different in the sense that device messenger can only communicate with objects that exists within that device whereas Global Messenger Subsystem can communicate with anything in game world outside the device. There is also no "Caller" but instead it is just event names for Device Messenger so if you stop listening it will stop all the listeners associated with the event. If you want an object to stop listening to an event, the only way is to destroy it and device manager will automatically take care of the cleaning.

Device Messenger is extensively used within the Operating System simulator plugin. You can check out Mail, Video Player etc bundled with the plugin to see example implementations.

Blueprint

To access the device you can either use Find Messenger from Operating System or Find Messenger for Device. Both will return a valid messenger object as long as the device is running.

Broadcasting, listening etc follows the same logic as of Global Messenger Subsystem.

warning

NOTE: If Event Name is set to None, ALL listeners regardless of their name will run their functions.

C++

To use Device Messenger Subsystem in C++, you must add Operating System module in your Build.cs.

Example:

PrivateDependencyModuleNames.AddRange(new string[] { "OperatingSystemSimulator" });

To broadcast an event, add the necessary includes in your cpp file and broadcast with the desired event name and payload:

#include "Devices/OperatingSystemDeviceMessenger.h"
#include "Statics/OperatingSystemStatics.h"

void ASomeActor::BroadcastFunction()
{
    // Grab the messenger from Operating System
    // Assume TargetOS is valid
    auto MessengerSubsystem = UOperatingSystemStatics::FindMessengerFromOperatingSystem(TargetOS);

    // Broadcast the event and with optional payload if required
    MessengerSubsystem->Broadcast(FName("MyEventName"), nullptr);

    // Optionally if you want to broadcast to *all* listeners, broadcast with None name.
    // MessengerSubsystem->Broadcast(NAME_None, nullptr);
}

To listen, we use the Begin Listen function.

In header file (.h)

// UFUNCTION macro is required.
UFUNCTION()
void SomeListenFunction(UObject* Payload);

In source file (.cpp)

#include "Devices/OperatingSystemDeviceMessenger.h"
#include "Statics/OperatingSystemStatics.h"

void AAnotherActor::AnotherFunction()
{
    // Grab the messenger from Operating System
    // Assume TargetOS is valid
    auto MessengerSubsystem = UOperatingSystemStatics::FindMessengerFromOperatingSystem(TargetOS);

    // Create the delegate.
    FOperatingSystemDeviceMessageDelegate CallbackDelegate;

    // Bind the delegate to the new function.
    CallbackDelegate.BindDynamic(this, &ThisClass::SomeListenFunction);

    // Now start listening the given event name.
    MessengerSubsystem->BeginListening(FName("MyEventName"), CallbackDelegate);
}