-
Notifications
You must be signed in to change notification settings - Fork 127
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Documentation for new code generator tags, august2024 #1727
Merged
Merged
Changes from all commits
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
9521be1
prototype documentation
nxtum 4eb05e6
updated docs
nxtum 8426f7c
added overview jsonrpc
nxtum 9320bf6
Merge branch 'master' into documentationCodeGen
nxtum f75f567
updated docs
nxtum e4dd6bc
Merge remote-tracking branch 'fork/documentationCodeGen' into documen…
nxtum File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -76,6 +76,165 @@ By default, when the `@json` tag is added, all methods in the COM-RPC interface | |
|
||
In older Thunder versions (<R4), JSON-RPC interfaces were defined using separate JSON schema files. These would then need to be manually wired up in the plugin. By using the code-generators, we can eliminate this step, making it much faster and easier to write plugins. It is no longer recommended to create JSON schema files for JSON-RPC interfaces. | ||
|
||
#### Overview | ||
|
||
* It is now possible to specify a separate JSON-RPC interface for handling connection issues and correct session management, and this will bring more options when the JSON-RPC interface deviates from the COM-RPC interface. | ||
|
||
* The JSON-RPC generator now supports the usage of nested "plain-old data"(POD) types (such as plain C structs) in the C++ interface. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Also nested PODs are supported |
||
* The JSON-RPC generator can now parse these structs and their usage in methods and generate a JSON-RPC interface for such cases. | ||
|
||
* `Core::hresult` is now supported as a return type from Thunder 5.0 onwards for JSONRPC and is strongly recommended to be used. | ||
|
||
* `@text` metatag has been extended to have more options to influence the names used in generated code. | ||
* For more details click [here](../tags/#text). | ||
|
||
* Float type is now supported in the IDL header files. | ||
|
||
* Fixed size arrays are now supported, for example:`array[10]` | ||
* See an example in [ICryptography](https://github.com/rdkcentral/ThunderInterfaces/blob/master/interfaces/ICryptography.h#L140) | ||
|
||
* `Core::instance_id` is now supported in the IDL header files. | ||
* It is presented as a 32/64 bit hexadecimal value in JSON-RPC. | ||
|
||
* `Core::Time` is now supported in the IDL header files. | ||
* It is presented as an [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) formatted string in JSON-RPC. | ||
|
||
* `Core::OptionalType<T>` 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 `/* @encode:bitmask */` [here](../tags/#encode). | ||
|
||
<hr/> | ||
|
||
#### 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. | ||
|
||
<hr/> | ||
|
||
#### 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. | ||
|
||
<hr/> | ||
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). | ||
|
||
<hr/> | ||
|
||
#### 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 <Interface>* 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. | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Perhaps we should also document that fixed size arrays are now supported (e.g. array[10], it is used in the new examples below) in certain cases.
We haven't yet documented although it was already possible but guess we should add it now that you can also use variable lenght arrays (so also for json rpc) : https://github.com/rdkcentral/ThunderInterfaces/blob/a229ea291aa52dc99e9c27839938f4f2af4a6190/interfaces/IDisplayInfo.h#L101