diff --git a/docs/plugin/interfaces/interfaces.md b/docs/plugin/interfaces/interfaces.md index 39af60faf..0b46a89b2 100644 --- a/docs/plugin/interfaces/interfaces.md +++ b/docs/plugin/interfaces/interfaces.md @@ -603,4 +603,145 @@ The auto-generated `JsonData_WiFi.h` file contains code that can convert from th ``` -Since there are no enums in this example interface, no `JsonEnums_WiFi.cpp` file was generated. \ No newline at end of file +Since there are no enums in this example interface, no `JsonEnums_WiFi.cpp` file was generated. + +## Advanced Topics + +### Serialized Types + +Serialized types are ... + + +`Core::OptionalType` allows a member to be optional, and must be used if a attribute is expected to be optional on JSON-RPC. + +Note: An unset value is not transmitted. + +A @default tag can be used to provide a value, in the case T is not set. See more [here](../tags/#default) + +
+ +#### Preventing Memory leaks + +A resource allocated by a remote client must still be freed in case the channel is disconnected, before the client was able to do it on its own. + +To deal with this, a method can receive a ```Core::JSONRPC::Context``` as a parameter. + +Amongst other things, the context includes the channel ID, which enables the association of the JSON-RPC call with the client. + +Note: Context must be defined as the first parameter, and will not be visible in the JSON-RPC messages. +```cpp +virtual Core::hresult Join(const Core::JSONRPC::Context& context, ...) = 0; +``` +Note: ```IConnection::INotification``` can be used to be notified of the dropped channels. + +Examples: + +View [Messenger.h](https://github.com/WebPlatformForEmbedded/ThunderNanoServicesRDK/blob/master/Messenger/Messenger.h#L254-L255) to see how ```Core::JSONRPC::Context``` is used. + +
+ +### Notification Registration + +Notification registration is a way of tracking updates on a notification: + +Tagging a notification with @statuslistener will emit additional code that will allow you to be notified when a JSON-RPC client has registered (or unregistered) from this notification. As a result, an additional IHandler interface is generated, providing the callbacks. + +Examples: + +In [IMessenger.H](https://github.com/rdkcentral/ThunderInterfaces/blob/master/interfaces/IMessenger.h#L95-L111), @statuslistener is used on two methods. + +
+This example will demonstrate the ability to be notified when a user performs a certain action. + +Suppose an interface "INotification" that contains a method "RoomUpdate", which tracks the availability of a room. The method is tagged with @statuslistener, which will allow for the creation of an "IHandler" interface. The "IHandler" interface will contain the required declaration of methods, to allow for notification registration tracking. + +```cpp +// @json 1.0.0 +struct EXTERNAL IMessenger { + virtual ~IMessenger() = default; + + /* @event */ + struct EXTERNAL INotification { + virtual ~INotification() = default; + + // @statuslistener + virtual void RoomUpdate(...) = 0; + } +} +``` +An example of a generated IHandler interface providing the callbacks from the RoomUpdate() function. + +```cpp +struct IHandler { + virtual ~IHandler() = default; + + virtual void OnRoomUpdateEventRegistration(const string& client, const + PluginHost::JSONRPCSupportsEventStatus::Status status) = 0; +} +``` + +Using the "IHandler" interface, its methods should be implemented to track the availability of the room. +``` cpp + +class Messenger : public PluginHost::IPlugin + , public JSONRPC::IMessenger + , public JSONRPC::JMessenger::IHandler { + + // JSONRPC::JMessenger::IHandler override + void OnRoomUpdateEventRegistration(const string& client, const + PluginHost::JSONRPCSupportsEventStatus::Status status) { + + if(status == Status::registered) { + + for (const string& room: _rooms) { + JMessenger::Event::RoomUpdate(...) + } + } + } +} +``` +For a more detailed view, visit [Messenger.h](https://github.com/WebPlatformForEmbedded/ThunderNanoServicesRDK/blob/master/Messenger/Messenger.h). + +
+ +### Object lookup + +Object lookup defines the ability to create a JSON-RPC interface to access dynamically created objects (or sessions). +This object interface is brought into JSON-RPC scope with a prefix. + +The format for this ability, is to use the tag '@lookup:[prefix]' on a method. + +Note: If 'prefix' is not set, then the name of the object interface is used instead. + +##### Example + +The signature of a lookup function must be: + +```cpp +virtual * Method(const uint32_t id) = 0; +``` + +An example of an IPlayer interface containing a playback session. Using tag @lookup, you are able to have multiple sessions, which can be differentiated by using JSON-RPC. + +```cpp +struct IPlayer { + struct IPlaybackSession { + virtual Core::hresult Play() = 0; + virtual Core::hresult Stop() = 0; + }; + + // @lookup:session + virtual IPlaySession* Session(const uint32_t id) = 0; + + virtual Core::hresult Create(uint32_t& id /* @out */) = 0; + virtual Core::hresult Configure(const string& config) = 0; +} +``` +An example of possible calls to the interface: the lookup method is used to convert the id to the object. + +``` +Player.1.configure +Player.1.create +Player.1.session#1::play +Player.1.session#1::stop +``` \ No newline at end of file diff --git a/docs/plugin/interfaces/tags.md b/docs/plugin/interfaces/tags.md index 61ff1ba99..0235240b6 100644 --- a/docs/plugin/interfaces/tags.md +++ b/docs/plugin/interfaces/tags.md @@ -107,7 +107,7 @@ Ddefines a literal as a known identifier (equivalent of `#define` in C++ code) |[@length](#length)|Specifies the expression to evaluate length of an array parameter (can be other parameter name, or constant, or math expression)| | No | Yes | Method Parameter| |[@maxlength](#maxlength)|Specifies a maximum buffer length value | | No | Yes |Method parameter| |[@default](#default)|Provides a default value for an unset variable | | Yes | Yes |Method parameter| -|[@encode:base64](#encode:base64)|Encodes C-Style arrays as JSON-RPC Base64 arrays | | Yes | Yes |Method parameter| +|[@encode:base64](#encode:base64)|Encodes C-Style arrays as JSON-RPC base64 arrays | | Yes | Yes |Method parameter| #### @in This tag will mark a parameter in a function as an input parameter. By default, all parameters in a function are treated as input paramter. @@ -216,6 +216,7 @@ In [IPerformance.h](https://github.com/rdkcentral/ThunderInterfaces/blob/5fa166b This tag should be associated with optional types. It provides a default value for JSON-RPC, even if no explicit value was set. Note: Unless a parameter is optional, it must be set. + Note: Currently, OptionalType does not work with C-Style arrays. ##### Example @@ -242,11 +243,11 @@ In [IController.h](https://github.com/rdkcentral/Thunder/blob/master/Source/plug #### @encode:base64 -This tag encodes C-Style arrays into JSON-RPC arrays as Base64 strings, on the condition that the array base is type uint8_t. +This tag encodes C-Style arrays into JSON-RPC arrays as base64 strings, on the condition that the array base is type `uint8_t`. ##### Example -In this example, C-Style uint8_t arrays are encoded as Base64. +In this example, C-Style `uint8_t` arrays are encoded as base64. ```cpp struct Fixated { @@ -530,6 +531,23 @@ This is particularly useful for avoiding clashes, especially if several interfac // @prefix source struct EXTERNAL ISource: virtual public Core::IUnknown { ``` + +
+ +#### @statuslistener + +Use this tag, to receive notifications when a JSON-RPC client has registered (or unregistered) from a notification. + +For more details, click [here](../interfaces/#notification-registration) + + +
+ +#### @lookup + +This tag is used on methods, to create a JSON-RPC interface that is dynamically accessing created objects (or sessions). + +For more details, click [here](../interfaces/#object-lookup)
@@ -633,89 +651,4 @@ This tag adds description about each return codes specified in the generated mar ##### Example In [IVolumeControl.h](https://github.com/rdkcentral/ThunderInterfaces/blob/5fa166bd17c6b910696c6113c5520141bcdea07b/interfaces/IVolumeControl.h#L54), it uses this tag to add description about the returned error code. -
- -### Advanced Topics - -#### @statuslistener - -Tagging a notification with @statuslistener will emit additional code that will allow you to be notified when a JSON-RPC client has registered (or unregistered) from this notification. - -As a result, an additional IHandler interface is generated, providing the callbacks. - -##### Example - -In [IMessenger.H](https://github.com/rdkcentral/ThunderInterfaces/blob/master/interfaces/IMessenger.h#L95-L111), the methods use this tag to enable notification changes. - -
- -In this example, a method with the tag @lookup is used, which will allow for the generation of an IHandler interface. - -```cpp -// @json 1.0.0 -struct EXTERNAL IMessenger { - virtual ~IMessenger() = default; - - /* @event */ - struct EXTERNAL INotification { - virtual ~INotification() = default; - - // @statuslistener - virtual void RoomUpdate() = 0; - } -} -``` -An example of a generated IHandler interface providing the callbacks from the RoomUpdate() function. - -```cpp -struct IHandler { - virtual ~IHandler() = default; - - virtual void OnRoomUpdateEventRegistration(const string& client, const - PluginHost::JSONRPCSupportsEventStatus::Status status) = 0; -} -``` -
- -#### @lookup - -This tag can be used on a method, to create a JSON-RPC interface that is accessing dynamically created objects (or sessions). This object interface is brought into JSON-RPC scope with a prefix. - -The format for this tag is '@lookup:[prefix]'. - -Note: If 'prefix' is not set, then the name of the object interface is used instead. - - -##### Example - -The signature of the lookup function must be: - -```cpp -virtual * Method(const uint32_t id) = 0; -``` - -An example of an IPlayer interface containing a playback session. Using tag @lookup, you are able to have multiple sessions, which can be differentiated by using JSON-RPC. - -```cpp -struct IPlayer { - struct IPlaybackSession { - virtual Core::hresult Play() = 0; - virtual Core::hresult Stop() = 0; - }; - - // @lookup:session - virtual IPlaySession* Session(const uint32_t id) = 0; - - virtual Core::hresult Create(uint32_t& id /* @out */) = 0; - virtual Core::hresult Configure(const string& config) = 0; -} -``` -An example of possible calls to the interface: the lookup method is used to convert the id to the object. - -``` -Player.1.configure -Player.1.create -Player.1.session#1::play -Player.1.session#1::stop -``` - +
\ No newline at end of file