We use proprietary and third party's cookies to improve your experience and our services, identifying your Internet Browsing preferences on our website; develop analytic activities and display advertising based on your preferences. If you keep browsing, you accept its use. You can get more information on our Cookie Policy
Cookies Policy
Cloud Rendering Open API Specification - FIWARE Forge Wiki

Cloud Rendering Open API Specification

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Protocol

The Renderer and the Web Client will communicate with the Web Service with a WebSocket connection. The service will act as a WebSocket server, this host information needs to be communicated or known by the renderer and client.

Messages

Basic Structure

All of the protocol messages are sent and received as JSON. The basic message structure is the following:

{
    "channel" : <message-channel-as-string>,
    "message" :
    {
        "type" : <message-type-as-string>,
        "data" : 
        {
            <message-data>
        }
    }
}

Channels

Each message in the protocol will hold a top level "channel" type. The message will have the channel as string, the number can be used internally by the GE implementation.

The message will always have a unique "type", so the channel type is not meant for message identification. It is intended for message flow control on the GE implementation, as you will most likely have separate logic handling each of the channel types.

{
    "Signaling"   : 1,
    "Room"        : 2,
    "State"       : 3,
    "Application" : 4
}

Types

The type is mean for message identification. Each message type have their own data layout/structure. The message will have the type as string, the number can be used internally by the GE implementation.

{
    // "State" channel
    "Registration"          : 1,
    "RendererStateChange"   : 2,

    // "Signaling" channel
    "Offer"                 : 10,
    "Answer"                : 11,
    "IceCandidates"         : 12,

    // "Room" channel
    "RoomAssigned"          : 20,
    "RoomUserJoined"        : 21,
    "RoomUserLeft"          : 22,
    
    // "Application" channel
    "RoomCustomMessage"     : 30,
    "PeerCustomMessage"     : 31
}

State

Registration

A renderer and a client needs to register itself to the Cloud Rendering Service, this is the first message that MUST be sent once the WebSocket connection has been established.

Renderer Registration

For the renderer registration implies that it is online and can be assigned to any room without a renderer by the service. The renderer will receive a RoomAssignedMessage response to a registration message.

The renderer may also choose to create a new private room. The intention here is that a renderer registers itself and wants to create a room, not be assigned as the renderer to any client room request. This allows the renderer to immediately get a new empty room and send the room information forward to clients it wants to invite to its rendering. This option is especially needed when a renderer (eg. web browser renderer implementation) wants to share its web camera or desktop feed with specific individual clients. It is then needed for the renderer to notify this intent to the service so the scenario can be supported.

Renderers creating their own rooms is very important for certain type of application that do not want to provide renderers just for anyone to use, but for an approach when the implementation is more in control who gets the room information and can join into a specific renderers room.

The "createPrivateRoom" boolean property is defaulted to false if not defined. The renderer MUST set this property to true if it wants a private room assignment after the registration.

Client Registration

For a client it is a request for a new room or if roomId is a non-empty string a the client will be joined to an existing room. The response for the registration message is a RoomAssignedMessage. This message will have the error code 2 (DoesNotExist) set if the requested room did not exist.

Any custom registration properties needs to be set to message.data. These custom properties can be used by the Cloud Rendering GE implementation for example for authentication logic.

// Web Client -> Cloud Rendering Service
{
    "channel" : "State",
    "message" :
    {
        "type" : "Registration",
        "data" : 
        {
            "registrant" : "client",
            "roomId"     : <optional-room-id-to-join-as-string>,

            // The remaining structure of the data is decided by the Cloud Rendering GE
            // implementation. For example auth tokens to authenticate the registrant.
            <application-specific-data>
        }
    }
}

// Renderer -> Cloud Rendering Service
{
    "channel" : "State",
    "message" :
    {
        "type" : "Registration",
        "data" : 
        {
            "registrant"        : "renderer",
            "createPrivateRoom" : <boolean>,

            // The remaining structure of the data is decided by the Cloud Rendering GE
            // implementation. For example auth tokens to authenticate the registrant.
            <application-specific-data>
        }
    }
}

RendererStateChange

This message is sent from renderer to the cloud rendering web service to inform about state changes.

// Valid renderer states
{
    "Offline" : 1, // Renderer is offline, new clients should not be redirected here.
    "Online"  : 2, // Renderer is online and ready to server new clients.
    "Full"    : 3  // Renderers client limit has been reached, no new clients should be redirected here.
}
{
    "channel" : "State",
    "message" :
    {
        "type" : "RendererStateChange",
        "data" : 
        {
            "state" : <state-id-as-number>
        }
    }
}

Signaling

Offer

The offer message is the first step in signaling a peer to peer WebRTC connection. It includes the offer senders SDP information and optionally ICE candidate(s) for the WebRTC connection setup. The appropriate response for this message is an Answer message.

ICE candidates may be empty, in that case they will be sent with separate IceCandidates message(s).

// Web Client and Renderer -> Cloud Rendering Service
{
    "channel" : "Signaling",
    "message" :
    {
        "type" : "Offer",
        "data" : 
        {
            // If not defined when sender is a web client
            // "renderer" is assumed by the web service.
            "receiverId" : <receiver-peer-id-as-string>,

            "sdp" :
            {
                "type" : <sdp-type-as-string>,
                "sdp"  : <sdp-as-string>
            },
            "iceCandidates" :
            [
                {
                    "sdpMLineIndex" : <ice-m-line-index-as-number>,
                    "sdpMid"        : <ice-sdp-mid-as-string>,
                    "candidate"     : <ice-candidate-as-string>
                },
                ...
            ]
        }
    }
}

// Cloud Rendering Service -> Web Client and Renderer
{
    "channel" : "Signaling",
    "message" :
    {
        "type" : "Offer",
        "data" : 
        {
            "receiverId" : <receiver-peer-id-as-string>,
            "senderId"   : <sender-peer-id-as-string>,

            "sdp" :
            {
                "type" : <sdp-type-as-string>,
                "sdp"  : <sdp-as-string>
            },
            "iceCandidates" :
            [
                {
                    "sdpMLineIndex" : <ice-m-line-index-as-number>,
                    "sdpMid"        : <ice-sdp-mid-as-string>,
                    "candidate"     : <ice-candidate-as-string>
                },
                ...
            ]
        }
    }
}

Answer

The answer message is the second step in signaling a peer to peer WebRTC connection. It includes the answer senders SDP information and optionally ICE candidate(s) for the WebRTC connection setup.

ICE candidates may be empty, in that case they will be sent with separate IceCandidates message(s).

// Web Client and Renderer -> Cloud Rendering Service
{
    "channel" : "Signaling",
    "message" :
    {
        "type" : "Answer",
        "data" : 
        {
            // If not defined when sender is a web client
            // "renderer" is assumed by the web service.
            "receiverId" : <receiver-peer-id-as-string>,

            "sdp" :
            {
                "type" : <sdp-type-as-string>,
                "sdp"  : <sdp-as-string>
            },
            "iceCandidates" :
            [
                {
                    "sdpMLineIndex" : <ice-m-line-index-as-number>,
                    "sdpMid"        : <ice-sdp-mid-as-string>,
                    "candidate"     : <ice-candidate-as-string>
                },
                ...
            ]
        }
    }
}

// Cloud Rendering Service -> Web Client and Renderer
{
    "channel" : "Signaling",
    "message" :
    {
        "type" : "Answer",
        "data" : 
        {
            "receiverId" : <receiver-peer-id-as-string>,
            "senderId"   : <sender-peer-id-as-string>,

            "sdp" :
            {
                "type" : <sdp-type-as-string>,
                "sdp"  : <sdp-as-string>
            },
            "iceCandidates" :
            [
                {
                    "sdpMLineIndex" : <ice-m-line-index-as-number>,
                    "sdpMid"        : <ice-sdp-mid-as-string>,
                    "candidate"     : <ice-candidate-as-string>
                },
                ...
            ]
        }
    }
}

IceCandidates

This message can be sent from peer to peer to inform the other party of ICE candidates for establishing the WebRTC connection

// Web Client and Renderer -> Cloud Rendering Service
{
    "channel" : "Signaling",
    "message" :
    {
        "type"   : "IceCandidates",
        "data"   : 
        {
            "receiverId" : <receiver-peer-id-as-string>,

            "iceCandidates" :
            [
                {
                    "sdpMLineIndex" : <ice-m-line-index-as-number>,
                    "sdpMid"        : <ice-sdp-mid-as-string>,
                    "candidate"     : <ice-candidate-as-string>
                },
                ...
            ]
        }
    }
}

// Cloud Rendering Service -> Web Client and Renderer
{
    "channel" : "Signaling",
    "message" :
    {
        "type" : "IceCandidates",
        "data" : 
        {
            "receiverId" : <receiver-peer-id-as-string>,
            "senderId"   : <sender-peer-id-as-string>,

            "iceCandidates" :
            [
                {
                    "sdpMLineIndex" : <ice-m-line-index-as-number>,
                    "sdpMid"        : <ice-sdp-mid-as-string>,
                    "candidate"     : <ice-candidate-as-string>
                },
                ...
            ]
        }
    }
}

Room

RoomAssigned

This message is sent as a response to Registration message.

The data contains the room id you have been assigned to and your unique peer id inside the room. If the error code is set to anything but 0 (NoError) the roomId and peerId properties SHOULD be omitted by the sender and SHOULD be ignored by the receiver if set to a value.

The error code will tell you why you could not be assigned to a room.

This message is also sent to the renderer once it is assigned to a room. The peer id CAN be omitted when the message is sent to a renderer.

This message is followed by a RoomUserJoined message that will have the full list of peer id:s currently in the channel. This set will also includes your own peer id that has been sent to you in this message.

// Valid room assignment errors
{
    "NoError"       : 0, // No errors, you have been assigned to "roomId".
    "ServiceError"  : 1, // Room could not be server, internal service error.
    "DoesNotExist"  : 2, // Requested room id does not exist. Send new request without room id to create a new room.
    "Full"          : 3  // Requested room is full, try again later.
}
{
    "channel" : "Room",
    "message" :
    {
        "type" : "RoomAssigned",
        "data" : 
        {
            "error"  : <error-as-number>,
            
            "roomId" : <room-id-as-string>,
            "peerId" : <your-peer-id-in-the-room-as-number>
        }
    }
}

RoomUserJoined

This message is sent when new user(s) join the current room you are assigned to.

This message MUST NOT be sent to any client or a renderer before they have been assigned to a room with a RoomAssigned message.

{
    "channel" : "Room",
    "message" :
    {
        "type" : "RoomUserJoined",
        "data" : 
        {
            "peerIds" :
            [
                <peer-id-1-as-string>,
                <peer-id-2-as-string>,
                ...
            ]
        }
    }
}  

RoomUserLeft

This message is sent when user(s) leave the current room you are assigned to.

This message MUST NOT be sent to any client or a renderer before they have been assigned to a room with a RoomAssigned message.

{
    "channel" : "Room",
    "message" :
    {
        "type" : "RoomUserLeft",
        "data" : 
        {
            "peerIds" :
            [
                <peer-id-1-as-string>,
                <peer-id-2-as-string>,
                ...
            ]
        }
    }
}

Application

RoomCustomMessage

This message can be used by the application to send custom message between clients, the Cloud Rendering Service and the Renderer in the same room.

The Service and Renderer do not have a peer id assigned to them, when you want to send messages to these two components you will use reserved special meaning string identifiers instead. The reserver string identifiers are "service" and "renderer". These identifiers can be encountered in the 'sender' property and can be used in the 'receivers' property.

You can send a 1-to-1 message by assigning the other peers id to peerIds, or 1-to-many by assigning multiple ids.

For 1-to-all the peerIds list can be empty, if empty the message will be sent to all other peers and the Renderer in the room. You don't need to fill the peerIds list with all the peer ids for each client in the room, this is done automatically by the service if the list is empty.

Any custom message properties MAY be set to message.data.payload.

Custom messages MUST NOT be sent before you have been assigned to a room with a RoomAssigned message.

The Cloud Rendering Service MUST inject the 'sender' property into the message before passing it forward to the receivers. Meaning that the sender SHOULD NOT set the 'sender' property to and if it will the service MUST override it.

{
    "channel" : "Application",
    "message" :
    {
        "type" : "RoomCustomMessage",
        "data" : 
        {
            // Service will inject this, does not needed to be filled 
            // on the client or the renderer when sending the message.
            "sender" : <sender-peer-or-reserved-id-as-string>,

            "receivers" :
            [
                <reserved-string-identifier-1>,
                ...
                <receiver-peer-1-id-as-string>,
                <receiver-peer-2-id-as-string>,
                ...
            ],

            "payload" :
            {
                // The structure of the data is decided by the application and the web client implementation.
                <application-specific-data>
            }
        }
    }
}

// Example 1: Client sends to all peers and the renderer in the room.
{
    "channel" : "Application",
    "message" :
    {
        "type" : "RoomCustomMessage",
        "data" : 
        {
            "payload" : { "nick" : "John Doe" }
        }
    }
}

// Example 2: Client sends to message to a single peer.
{
    "channel" : "Application",
    "message" :
    {
        "type" : "RoomCustomMessage",
        "data" : 
        {
            "receivers"  : [ "2" ]
            "payload"    :
            { 
                "type"    : "PrivateMessage",
                "message" : "Hey, long time no see. Whats up?"
            }
        }
    }
}

// Example 3: Client sends message to peers 3, 5 and the renderer
{
    "channel" : "Application",
    "message" :
    {
        "type" : "RoomCustomMessage",
        "data" : 
        {
            "receivers"  : [ "renderer", "3", "5" ],
            "payload"    :
            {
                "message" : "Hello my name is John",
                "nick"    : "John Doe"
            }
        }
    }
}

// Example 4: Renderer sending a message to the Service
{
    "channel" : "Application",
    "message" :
    {
        "type" : "RoomCustomMessage",
        "data" : 
        {
            "receivers"  : [ "service" ],
            "payload"    :
            {
                "type"   : "KickUser",
                "peerId" : 2
            }
        }
    }
}

PeerCustomMessage

This message can be used by the application to send custom message between any two peers via a WebRTC data channel. This message does not contain sender or receiver id information because it is never relayed via the web service. The needed sender information is known from the WebRTC protocol by the application handling the messages.

These data channel messages should be used when there is no need for one-to-many communication and when you require real time/very frequent communication. The data channel skips the overhead and latency that is added by relaying the message via the web service with WebSocket.

Any custom message properties MAY be set to message.data.payload.

{
    "channel" : "Application",
    "message" :
    {
        "type" : "PeerCustomMessage",
        "data" :
        {
            "payload" :
            {
                // The structure of the data is decided by the application and the web client implementation.
                <application-specific-data>
            }
        }
    }
}
Personal tools
Create a book