Skip to content

Latest commit

 

History

History
364 lines (266 loc) · 9.8 KB

MessengerPlugin.md

File metadata and controls

364 lines (266 loc) · 9.8 KB
Raw

Messenger Plugin

Version: 1.0

Status: ⚫⚪⚪

Messenger plugin for WPEFramework.

Table of Contents

Introduction

Scope

This document describes purpose and functionality of the Messenger plugin. It includes detailed specification of its configuration, methods provided and notifications sent.

Case Sensitivity

All identifiers on the interface described in this document are case-sensitive. Thus, unless stated otherwise, all keywords, entities, properties, relations and actions should be treated as such.

Acronyms, Abbreviations and Terms

The table below provides and overview of acronyms used in this document and their definitions.

Acronym Description
API Application Programming Interface
HTTP Hypertext Transfer Protocol
JSON JavaScript Object Notation; a data interchange format
JSON-RPC A remote procedure call protocol encoded in JSON

The table below provides and overview of terms and abbreviations used in this document and their definitions.

Term Description
callsign The name given to an instance of a plugin. One plugin can be instantiated multiple times, but each instance the instance name, callsign, must be unique.

References

Ref ID Description
HTTP HTTP specification
JSON-RPC JSON-RPC 2.0 specification
JSON JSON specification
WPEF WPEFramework API Reference

Description

The Messenger allows exchanging text messages between users gathered in virtual rooms. The rooms are dynamically created and destroyed based on user attendance. Upon joining a room the client receives a unique token (room ID) to be used for sending and receiving the messages.

The plugin is designed to be loaded and executed within the WPEFramework. For more information on WPEFramework refer to [WPEF].

Configuration

The table below lists configuration options of the plugin.

Name Type Description
callsign string Plugin instance name (default: Messenger)
classname string Class name: Messenger
locator string Library name: libWPEFrameworkMessenger.so
autostart boolean Determines if the plugin is to be started automatically along with the framework

Methods

The following methods are provided by the Messenger plugin:

Messenger interface methods:

Method Description
join Joins a messaging room
leave Leaves a messaging room
send Sends a message to a room

join method

Joins a messaging room

Description

Use this method to join a room. If the specified room does not exist, then it will be created.

Also see: userupdate

Parameters

Name Type Description
params object
params.user string User name to join the room under (must not be empty)
params.room string Name of the room to join (must not be empty)

Result

Name Type Description
result object
result.roomid string Unique ID of the room

Errors

Code Message Description
5 ERROR_ILLEGAL_STATE User name is already taken (i.e. the user has already joined the room)
30 ERROR_BAD_REQUEST User name or room name was invalid

Example

Request

{
    "jsonrpc": "2.0", 
    "id": 1234567890, 
    "method": "Messenger.1.join", 
    "params": {
        "user": "Bob", 
        "room": "Lounge"
    }
}

Response

{
    "jsonrpc": "2.0", 
    "id": 1234567890, 
    "result": {
        "roomid": "1e217990dd1cd4f66124"
    }
}

leave method

Leaves a messaging room

Description

Use this method to leave a room. The room ID becomes invalid after this call. If there are no more users, the room will be destroyed and related resources freed.

Also see: userupdate

Parameters

Name Type Description
params object
params.roomid string ID of the room to leave

Result

Name Type Description
result null Always null

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY The given room ID was invalid

Example

Request

{
    "jsonrpc": "2.0", 
    "id": 1234567890, 
    "method": "Messenger.1.leave", 
    "params": {
        "roomid": "1e217990dd1cd4f66124"
    }
}

Response

{
    "jsonrpc": "2.0", 
    "id": 1234567890, 
    "result": null
}

send method

Sends a message to a room

Description

Use this method to send a message to a room.

Also see: message

Parameters

Name Type Description
params object
params.roomid string ID of the room to send the message to
params.message string The message content to send

Result

Name Type Description
result null Always null

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY The given room ID was invalid

Example

Request

{
    "jsonrpc": "2.0", 
    "id": 1234567890, 
    "method": "Messenger.1.send", 
    "params": {
        "roomid": "1e217990dd1cd4f66124", 
        "message": "Hello!"
    }
}

Response

{
    "jsonrpc": "2.0", 
    "id": 1234567890, 
    "result": null
}

Notifications

Notifications are autonomous events, triggered by the internals of the plugin, and broadcasted via JSON-RPC to all registered observers. Refer to [WPEF] for information on how to register for a notification.

The following events are provided by the Messenger plugin:

Messenger interface events:

Event Description
roomupdate Notifies about room status updates
userupdate Notifies about user status updates
message Notifies about new messages in a room

roomupdate event

Notifies about room status updates

Description

Register to this event to be notified about room status updates. Immediately after registering to this notification the listener will sequentially receive updates of all rooms that have been created so far.

Parameters

Name Type Description
params object
params.room string Name of the room this notification relates to
params.action string Specifies the room status change, e.g. created or destroyed (must be one of the following: created, destroyed)

Example

{
    "jsonrpc": "2.0", 
    "method": "client.events.1.roomupdate", 
    "params": {
        "room": "Lounge", 
        "action": "created"
    }
}

userupdate event

Notifies about user status updates.

Description

Register to this event to be notified about room status updates. Immediately after registering to this notification the listener will sequentially receive updates of all users that have joined the room so far.

Parameters

Name Type Description
params object
params.user string Name of the user that has this notification relates to
params.action string Specifies the user status change, e.g. join or leave a room (must be one of the following: joined, left)

The room ID shall be passed within the designator, e.g. 1e217990dd1cd4f66124.client.events.1.

Example

{
    "jsonrpc": "2.0", 
    "method": "1e217990dd1cd4f66124.client.events.1.userupdate", 
    "params": {
        "user": "Bob", 
        "action": "joined"
    }
}

message event

Notifies about new messages in a room

Description

Register to this event to be notified about new messages in a room.

Parameters

Name Type Description
params object
params.user string Name of the user that has sent the message
params.message string Content of the message

The room ID shall be passed within the designator, e.g. 1e217990dd1cd4f66124.client.events.1.

Example

{
    "jsonrpc": "2.0", 
    "method": "1e217990dd1cd4f66124.client.events.1.message", 
    "params": {
        "user": "Bob", 
        "message": "Hello!"
    }
}