Auki::Vikja::Vikja

The Vikja module implements a centralized key-value store in the form of a dictionary of dictionaries. The keys of the outer dictionary are Entity ids while the keys of the inner dictionaries are strings. The inner value type is EntityAction, comprising an arbitrary byte array, a timestamp, as well as the outer and inner keys that index the EntityAction. More...

Inherits from AukiModule

Public Functions

	Name
	Vikja(IConjureKit conjureKit) Constructor - initializes and registers Vikja as an AukiModule. Takes as argument an object implementing the IConjureKit interface, e.g., a ConjureKit instance.
IDictionary< string, EntityAction >	GetEntityActions(uint entityId) Retrieves the inner dictionary that holds EntityActions associated to a given Entity. Returns null if the Entity id is not a key of the outer dictionary.
EntityAction	GetEntityAction(uint entityId, string actionName) Retrieves an EntityAction. Returns null if either key is missing.
override Tuple< uint, uint >	_GetMessageTypeRange() (Internal) Returns the message type range expected by the module.
override void	_HandleMessage(uint messageType, byte[] data) (Internal) Handles a Hagall message. Invoked by the IConjureKit-implementing object the module was constructed with.
void	RequestAction(uint entityId, string name, byte[] data, Action< EntityAction > onComplete, Action< string > onError) Updates the Vikja value of outer key entityId and inner key name to a new EntityAction whose payload is a given byte array and an automatically generated timestamp.
void	RequestAction(uint entityId, string name, byte[] data, Timestamp timestamp, Action< EntityAction > onComplete, Action< string > onError) Updates the Vikja value of outer key entityId and inner key name to a new EntityAction whose payload is a given byte array and a custom timestamp.

Public Attributes

	Name
Action< EntityAction >	OnEntityAction Callback produced for every update to the Vikja store. The participant who is responsible for the update does not receive the callback.

Detailed Description

class Auki::Vikja::Vikja;

The Vikja module implements a centralized key-value store in the form of a dictionary of dictionaries. The keys of the outer dictionary are Entity ids while the keys of the inner dictionaries are strings. The inner value type is EntityAction, comprising an arbitrary byte array, a timestamp, as well as the outer and inner keys that index the EntityAction.

Finer points:

• There is only one Vikja instance, shared by all participants.
• Joining participants are given the current contents Vikja store as part of the session state.
• Each update is broadcast to all participants via a callback, except for the participant that effected the update.
• A participant can only update the dictionary of an entity that it owns.
• The Vikja module constructor takes an IConjureKit interface instance as argument (e.g., a ConjureKit instance). The Vikja constructor must be run before that object's .Connect() method is called.

Public Functions Documentation

function Vikja

Vikja(
    IConjureKit conjureKit
)

Constructor - initializes and registers Vikja as an AukiModule. Takes as argument an object implementing the IConjureKit interface, e.g., a ConjureKit instance.

Parameters:

• conjureKit IConjureKit-implementing object

function GetEntityActions

IDictionary< string, EntityAction > GetEntityActions(
    uint entityId
)

Retrieves the inner dictionary that holds EntityActions associated to a given Entity. Returns null if the Entity id is not a key of the outer dictionary.

Parameters:

• entityId Entity id

Return: A IDictionary<string, EntityAction> or null.

function GetEntityAction

EntityAction GetEntityAction(
    uint entityId,
    string actionName
)

Retrieves an EntityAction. Returns null if either key is missing.

Parameters:

• entityId Entity id
• actionName Action name

Return: An EntityAction, or null.

function _GetMessageTypeRange

override Tuple< uint, uint > _GetMessageTypeRange()

(Internal) Returns the message type range expected by the module.

Return: Message type range tuple

function _HandleMessage

override void _HandleMessage(
    uint messageType,
    byte[] data
)

(Internal) Handles a Hagall message. Invoked by the IConjureKit-implementing object the module was constructed with.

Parameters:

• messageType Message type
• data Byte array payload

function RequestAction

void RequestAction(
    uint entityId,
    string name,
    byte[] data,
    Action< EntityAction > onComplete,
    Action< string > onError
)

Updates the Vikja value of outer key entityId and inner key name to a new EntityAction whose payload is a given byte array and an automatically generated timestamp.

Parameters:

• entityId Entity id
• name Action name
• data Byte array payload
• onComplete Callback invoked after a successful update receiving the newly created EntityAction
• onError Callback invoked after a failed update receiving the error message

The update will fail if the participant generating the request is not the owner of the entity or if the store contains an existing EntityAction at (entityId, name) with a more recent timestamp.

Sample:

_vikja.RequestAction(
    entityId,
    "ACTION_NAME",
    Encoding.ASCII.GetBytes("CONTENT"),
    action => {
        Debug.Log($"Received request action success with {action.Name}");
    },
    s => {
        Debug.Log($"Received request action error: {s}");
    }
);

function RequestAction

void RequestAction(
    uint entityId,
    string name,
    byte[] data,
    Timestamp timestamp,
    Action< EntityAction > onComplete,
    Action< string > onError
)

Updates the Vikja value of outer key entityId and inner key name to a new EntityAction whose payload is a given byte array and a custom timestamp.

Parameters:

• entityId Entity id
• name Action name
• data Byte array payload
• timestamp Custom Timestamp payload
• onComplete Callback invoked after a successful update receiving the newly created EntityAction
• onError Callback invoked after a failed update receiving the error message

The update will fail if the participant generating the request is not the owner of the entity or if the store contains an existing EntityAction at (entityId, name) with a more recent timestamp.

Sample:

_vikja.RequestAction(
    entityId,
    "ACTION_NAME",
    Encoding.ASCII.GetBytes("CONTENT"),
    Timestamp.FromDateTimeOffset(DateTimeOffset.UtcNow),
    action => {
        Debug.Log($"Received request action success with {action.Name}");
    },
    s => {
        Debug.Log($"Received request action error: {s}");
    }
);

Public Attributes Documentation

variable OnEntityAction

Action< EntityAction > OnEntityAction;

Callback produced for every update to the Vikja store. The participant who is responsible for the update does not receive the callback.

Sample:

_vikja.OnEntityAction += (
    action => Debug.Log($"Received action {action.Name} for entity {action.EntityId}.");
)