From 9521be1deadbf75bd1f81c5c5551683270a6bac4 Mon Sep 17 00:00:00 2001 From: nxtumUbun Date: Fri, 16 Aug 2024 03:54:57 -0700 Subject: [PATCH 1/4] prototype documentation --- docs/plugin/interfaces/tags.md | 178 ++++++++++++++++++++++++++++++++- 1 file changed, 176 insertions(+), 2 deletions(-) diff --git a/docs/plugin/interfaces/tags.md b/docs/plugin/interfaces/tags.md index f58701a8e..61ff1ba99 100644 --- a/docs/plugin/interfaces/tags.md +++ b/docs/plugin/interfaces/tags.md @@ -106,6 +106,8 @@ Ddefines a literal as a known identifier (equivalent of `#define` in C++ code) |[@interface](#interface)| Specifies a parameter holding interface ID value for void* interface passing | | Yes | No |Method paramter| |[@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| #### @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. @@ -208,6 +210,64 @@ When used with `@inout` it will use different buffer for output depending upon t ##### Example In [IPerformance.h](https://github.com/rdkcentral/ThunderInterfaces/blob/5fa166bd17c6b910696c6113c5520141bcdea07b/interfaces/IPerformance.h#L32) it specifies, the maximum length for the buffer. +
+ +#### @default +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 + +In this example class, the OptionalType members have a default value that would be transmitted incase their values have not been set. + +```cpp +struct Store { + enum sizetype: uint8_t { + S, M, L + }; + + Core::OptionalType Brand /* @default:"unknown" */; + Core::OptionalType Size /* @default: M */; +}; + +virtual Core::hresult Shirt(const Core::OptionalType& London) = 0; +``` +
+ +In [IController.h](https://github.com/rdkcentral/Thunder/blob/master/Source/plugins/IController.h#L78) it specifies, the default value assigned incase the parameter is not set. + +
+ +#### @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. + +##### Example + +In this example, C-Style uint8_t arrays are encoded as Base64. + +```cpp +struct Fixated { + struct BlueToothInfo { + uint8_t Addr[6] /* encode:base64 */; + uint32_t UUIDs[8]; + string Descriptions[8]; + }; + +Bluetooth BtAddr[5]; +uint8_t Edid[128] /*encode:base64 */; +}; + +``` + +
+ +In [IDisplayInfo.h](https://github.com/rdkcentral/ThunderInterfaces/blob/a229ea291aa52dc99e9c27839938f4f2af4a6190/interfaces/IDisplayInfo.h#L101), the EDID data parameter is encoded. + + +
### JSON-RPC Related Tags @@ -226,6 +286,9 @@ In [IPerformance.h](https://github.com/rdkcentral/ThunderInterfaces/blob/5fa166b |[@opaque](#opaque)| Indicates that a string parameter is an opaque JSON object | | No | Yes |Method parameter| |[@alt](#alt)| Provides an alternative name a method can by called by | | No | Yes |Method| |[@text](#text)| Renames identifier Method, Parameter, PoD Member, Enum, Interface | | No | Yes |Enum, Method parameter, Method name, PoD member, Interface | +|[@prefix](#prefix)| Prepends identifier for all JSON-RPC methods and properties in a class | | No | Yes | Class | +|[@statuslistener](#statuslistener)| Notifies when a JSON-RPC client registers/unregisters from an notification | | No | Yes | Method | +|[@lookup](#lookup)| Creates JSON-RPC interface to access dynamically created sessions | | No | Yes | Method | #### @json This tag helps to generate JSON-RPC files for the given Class/Struct/enum. @@ -397,8 +460,19 @@ Indicates the string parameter contains a JSON document that should not be deser #### @alt Provide an alternative name for the method. JSON-RPC methods will be generated for both the actual function name and the alternative name +Note: @text, @alt, @deprecated can be used together. + ##### Example -[IController](https://github.com/rdkcentral/Thunder/blob/R4.3/Source/plugins/IController.h#L38) uses @alt for the `Reboot()` method to generate an alternatively named method called `Harakiri` (for legacy reasons) + +Methods, properties and notifications can be marked by using: +```cpp +// @alt +// @alt:deprecated +// @alt:obsolete +``` +
+ +[IController.h](https://github.com/rdkcentral/Thunder/blob/R4.3/Source/plugins/IController.h#L38) uses @alt for the `Reboot()` method to generate an alternatively named method called `Harakiri` (for legacy reasons)
@@ -442,10 +516,23 @@ In this example now for all enums, method names, method parameters and PoD membe /* @json 1.0.0 @text:keep */ struct EXTERNAL IExample : virtual public Core::IUnknown { ``` - +
+#### @prefix +Use this tag on a class to prepend all JSON-RPC methods with a prefix identifier. This is an alternative to using multiple @text tags. +In this example, all registered methods would contain the prefix source::. +This is particularly useful for avoiding clashes, especially if several interfaces are implemented by the same plugin. + +```cpp +// @json 1.0.0 +// @prefix source +struct EXTERNAL ISource: virtual public Core::IUnknown { +``` + + +
### JSON-RPC Documentation Related Tags @@ -545,3 +632,90 @@ 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 +``` + From 4eb05e6c23a6093214a75686f824e353540b778c Mon Sep 17 00:00:00 2001 From: nxtumUbun Date: Wed, 21 Aug 2024 07:01:45 -0700 Subject: [PATCH 2/4] updated docs --- docs/plugin/interfaces/interfaces.md | 143 ++++++++++++++++++++++++++- docs/plugin/interfaces/tags.md | 111 +++++---------------- 2 files changed, 164 insertions(+), 90 deletions(-) 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 From 8426f7c03f6e56b01d87ac4882027616738d24db Mon Sep 17 00:00:00 2001 From: nxtumUbun Date: Thu, 22 Aug 2024 05:00:25 -0700 Subject: [PATCH 3/4] added overview jsonrpc --- docs/plugin/interfaces/interfaces.md | 302 ++++++++++++++------------- docs/plugin/interfaces/tags.md | 6 +- 2 files changed, 163 insertions(+), 145 deletions(-) diff --git a/docs/plugin/interfaces/interfaces.md b/docs/plugin/interfaces/interfaces.md index 0b46a89b2..abfdc1512 100644 --- a/docs/plugin/interfaces/interfaces.md +++ b/docs/plugin/interfaces/interfaces.md @@ -76,6 +76,165 @@ By default, when the `@json` tag is added, all methods in the COM-RPC interface In older Thunder versions (` allows a member to be optional (this superseded @optional), and must be used if an attribute is expected to be optional on JSON-RPC. In COM-RPC the OptionalType can be used to see if a value was set, and in JSON-RPC it is then allowed to omit this parameter. + * A @default tag can be used to provide a value, in the case T is not set. See more [here](../tags/#default). + * Note: Currently, OptionalType does not work with C-Style arrays. + +* JSON-RPC supports the usage of bitmask enums (a combination of enum values can be set in the same enum parameter at the same time). + * This is mapped as an array of values in the JSON-RPC interface. + * See more information about `/* bitmask */` [here](../tags/#bitmask). + +
+ +#### Preventing Memory leaks + +A resource allocated by a remote client must still be freed in case the channel is disconnected before the client is 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 +``` + ### Code Generation The code generation tooling for Thunder lives in the [ThunderTools](https://github.com/rdkcentral/ThunderTools) repository. These tools are responsible for the generation of ProxyStub implementations for COM-RPC, JSON-RPC interfaces, JSON data types, and documentation. @@ -603,145 +762,4 @@ 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. - -## 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 +Since there are no enums in this example interface, no `JsonEnums_WiFi.cpp` file was generated. \ No newline at end of file diff --git a/docs/plugin/interfaces/tags.md b/docs/plugin/interfaces/tags.md index 0235240b6..4f36396cd 100644 --- a/docs/plugin/interfaces/tags.md +++ b/docs/plugin/interfaces/tags.md @@ -106,7 +106,7 @@ Ddefines a literal as a known identifier (equivalent of `#define` in C++ code) |[@interface](#interface)| Specifies a parameter holding interface ID value for void* interface passing | | Yes | No |Method paramter| |[@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| +|[@default](#default)|Provides a default value for an unset optional type | | Yes | Yes |Method parameter| |[@encode:base64](#encode:base64)|Encodes C-Style arrays as JSON-RPC base64 arrays | | Yes | Yes |Method parameter| #### @in @@ -289,7 +289,7 @@ In [IDisplayInfo.h](https://github.com/rdkcentral/ThunderInterfaces/blob/a229ea2 |[@text](#text)| Renames identifier Method, Parameter, PoD Member, Enum, Interface | | No | Yes |Enum, Method parameter, Method name, PoD member, Interface | |[@prefix](#prefix)| Prepends identifier for all JSON-RPC methods and properties in a class | | No | Yes | Class | |[@statuslistener](#statuslistener)| Notifies when a JSON-RPC client registers/unregisters from an notification | | No | Yes | Method | -|[@lookup](#lookup)| Creates JSON-RPC interface to access dynamically created sessions | | No | Yes | Method | +|[@lookup](#lookup)| Creates a JSON-RPC interface to access dynamically created sessions | | No | Yes | Method | #### @json This tag helps to generate JSON-RPC files for the given Class/Struct/enum. @@ -523,7 +523,7 @@ In this example now for all enums, method names, method parameters and PoD membe #### @prefix Use this tag on a class to prepend all JSON-RPC methods with a prefix identifier. This is an alternative to using multiple @text tags. -In this example, all registered methods would contain the prefix source::. +In this example, all registered methods would contain the prefix `source::` This is particularly useful for avoiding clashes, especially if several interfaces are implemented by the same plugin. ```cpp From f75f567c53416090ff8a76f487e8dfba2fec890b Mon Sep 17 00:00:00 2001 From: nxtumUbun Date: Sun, 25 Aug 2024 23:40:16 -0700 Subject: [PATCH 4/4] updated docs --- docs/plugin/interfaces/interfaces.md | 10 ++-- docs/plugin/interfaces/tags.md | 83 +++++++++++++++++----------- 2 files changed, 56 insertions(+), 37 deletions(-) diff --git a/docs/plugin/interfaces/interfaces.md b/docs/plugin/interfaces/interfaces.md index abfdc1512..83c96aef2 100644 --- a/docs/plugin/interfaces/interfaces.md +++ b/docs/plugin/interfaces/interfaces.md @@ -80,19 +80,19 @@ In older Thunder versions ( diff --git a/docs/plugin/interfaces/tags.md b/docs/plugin/interfaces/tags.md index 4f36396cd..18ae20d7d 100644 --- a/docs/plugin/interfaces/tags.md +++ b/docs/plugin/interfaces/tags.md @@ -107,7 +107,6 @@ 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 optional type | | 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. @@ -239,35 +238,6 @@ virtual Core::hresult Shirt(const Core::OptionalType& London) = 0; In [IController.h](https://github.com/rdkcentral/Thunder/blob/master/Source/plugins/IController.h#L78) it specifies, the default value assigned incase the parameter is not set. -
- -#### @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`. - -##### Example - -In this example, C-Style `uint8_t` arrays are encoded as base64. - -```cpp -struct Fixated { - struct BlueToothInfo { - uint8_t Addr[6] /* encode:base64 */; - uint32_t UUIDs[8]; - string Descriptions[8]; - }; - -Bluetooth BtAddr[5]; -uint8_t Edid[128] /*encode:base64 */; -}; - -``` - -
- -In [IDisplayInfo.h](https://github.com/rdkcentral/ThunderInterfaces/blob/a229ea291aa52dc99e9c27839938f4f2af4a6190/interfaces/IDisplayInfo.h#L101), the EDID data parameter is encoded. - -
### JSON-RPC Related Tags @@ -282,7 +252,7 @@ In [IDisplayInfo.h](https://github.com/rdkcentral/ThunderInterfaces/blob/a229ea2 |[@event](#event)|Marks a class as JSON notification | | No| Yes|Class| |[@property](#property)|Marks a method as a property ||No|Yes| Method| |[@iterator](#iterator)|Marks a class as an iterator | | Yes| Yes|Class| -|[@bitmask](#bitmask)| Indicates that enumerator lists should be packed into into a bit mask | | No | Yes |Method parameter| +|[@bitmask](#bitmask)| Indicates that enumerator lists should be packed into into a bit mask | Yes| No | Yes |Method parameter| |[@index](#index)|Marks an index parameter to a property or notification | | No| Yes|Method paramter| |[@opaque](#opaque)| Indicates that a string parameter is an opaque JSON object | | No | Yes |Method parameter| |[@alt](#alt)| Provides an alternative name a method can by called by | | No | Yes |Method| @@ -290,6 +260,7 @@ In [IDisplayInfo.h](https://github.com/rdkcentral/ThunderInterfaces/blob/a229ea2 |[@prefix](#prefix)| Prepends identifier for all JSON-RPC methods and properties in a class | | No | Yes | Class | |[@statuslistener](#statuslistener)| Notifies when a JSON-RPC client registers/unregisters from an notification | | No | Yes | Method | |[@lookup](#lookup)| Creates a JSON-RPC interface to access dynamically created sessions | | No | Yes | Method | +|[@encode](#encode)|Encodes data into a different format | | Yes | Yes |Method parameter| #### @json This tag helps to generate JSON-RPC files for the given Class/Struct/enum. @@ -549,7 +520,55 @@ This tag is used on methods, to create a JSON-RPC interface that is dynamically For more details, click [here](../interfaces/#object-lookup) - +
+ +#### @encode + +This tag encodes data into an alternate format. + +* `@encode:base64` encodes arrays as base64 JSON-RPC arrays, on the condition that the array base is type `uint8_t`. + +##### Example + +In this example, C-Style `uint8_t` arrays are encoded as base64. + +```cpp +struct Fixated { + struct BlueToothInfo { + uint8_t Addr[6] /* encode:base64 */; + uint32_t UUIDs[8]; + string Descriptions[8]; + }; + +Bluetooth BtAddr[5]; +uint8_t Edid[128] /*encode:base64 */; +}; + +``` + +In [IDisplayInfo.h](https://github.com/rdkcentral/ThunderInterfaces/blob/a229ea291aa52dc99e9c27839938f4f2af4a6190/interfaces/IDisplayInfo.h#L101), the EDID data parameter is encoded. + +
+ +* `@encode:bitmask` encodes enumerator lists into into a bit mask. + +##### Example + +In this example, a tagged enum is treated as a bitmasked list. + +```cpp +enum soundmode : uint8_t { + MONO = 1, + STEREO = 2, + SURROUND = 4 +}; + +virtual Core::hresult SupportedSoundModes(soundmode &sm /* @out @encode:bitmask */) = 0; +``` + +Example list: +`["mono", "stereo"]` +
### JSON-RPC Documentation Related Tags