Commit 95ef31ac authored by Albert Vaca Cintora's avatar Albert Vaca Cintora

Documentation

Added a README to each plugin explaining the content of the packages they
send and receive
Explained the format of encrypted packages.
parent 4bd5d2e4
......@@ -40,17 +40,18 @@ are sent from one device to another (via a DeviceLink) serialized in json.
The basic structure of a NetworkPackage is the following:
{
"id": 123456789,
"type": "org.kde.whatever",
"body": {
"id": 123456789,
"type": "org.kde.whatever",
"body": {
},
"version": 5
},
"version": 5
}
Each type of package defines what it should contain inside its "body", so only
the emisor Plugin and receiver Plugin of this type of package need agree about
its content.
the emisor plugin and receiver plugin of this type of package need agree about
its content. Each plugin should provide a README explaining what does it write
in the "body" section, to ease porting to other platforms.
If the package has a payload attached, it will also contain two more fields:
"payloadSize": The size of the file, or -1 if it is a stream without known end
......@@ -60,7 +61,16 @@ If the package has a payload attached, it will also contain two more fields:
Encrypted network packages have the following format:
//TODO
"type": is always set to "kdeconnect.encrypted".
"id": contains a new valid id (ie: not the same id as the unencrypted package).
"version": contains the package version.
"body": contains a "data" array that carries the original package encrypted.
The "data" array is filled the following way:
1. The original package is serialized.
2. The serialized string is divided in chunks small enough to be encrypted with
the other device's public key.
3. Each chunk is encrypted and appended to the array in order.
//TODO: Document the possible contents written for each plugin in the body part
This plugins receives packages with type "kdeconnect.battery" and reads the
following fields:
isCharging (boolean): If the battery of the peer device is charging
currentCharge (int): The charge % of the peer device
<TODO>
Symmetrically, it sends its own battery information in packages with the same
format.
</TODO>
It also sends packages with type kdeconnect.battery and a field "request": true,
to ask the peer device to send a package like the mentioned above, and should
also answer this same kind of packages with its own information.
If the battery is low and discharging, it will notify the user.
When the clipboard changes, it sends a package with type kdeconnect.clipboard
and the field "content" (string) containing the new clipboard content.
When it receivest a package of the same kind, it should update the system
clipboard with the received content, so the clipboard in both devices always
have the same content.
This plugin is symmetric to its counterpart in the other device: both have the
same behaviour.
It receives a packages with type kdeconnect.filetransfer. If they have a payload
attached, it will download it as a file with the filename set in the field
"filename" (string). If that field is not set it should generate a filename.
<TODO>
If the content transferred is text, it can be sent in a field "text" (string)
instead of an attached payload. In that case, this plugin opens a text editor
with the content instead of saving it as a file.
</TODO>
This plugin controls the playback of mpris-enabled applications in this device,
commanded by its counterpart in the other device that acts as a remote control.
That means both plugins are not symmetrical.
This plugins receives and sends packages with type kdeconnect.mpris.
It keeps a list of detected players it can control via MPRIS. When it receives
a package that contains the boolean "requestPlayerList" set to true, it will
send back the list of players in an array named "playerList". If a new player is
detected or a known one dissappears, it should also send this list. Note that
players are identified only by its name (its MPRIS Identity), so there can not
be two players with the same display name.
This plugins also reports the current song, extracted from MPRIS Metadata. It
should send it when it changes or when receiving a package containing a boolean
"requestNowPlaying" set to true.
The remote devices can send packages with commands to one of the players. Those
packages will contain a string "player" with the name of the player they want to
command and a string "action" with the name of an MPRIS call (like "Play",
"Next"...).
This plugin can also control the system volume. The peer device can send a
package with "requestVolume" set to true to ask for the current volume, or send
a package with "setVolume" set to an integer in the range [0,100] to change it.
This plugin listens to packages with type "kdeconnect.notification" that will
contain all the information of the other device notifications.
The other device will report us every notification that is created or dismissed,
so we can keep in sync a local list of notifications.
At the beginning we can request the already existing notifications by sending a
package with the boolean "request" set to true.
The received packages will contain the following fields:
"id" (string): A unique notification id.
"appName" (string): The app that generated the notification
"ticker" (string): The title or headline of the notification.
"isClearable" (boolean): True if we can request to dismiss the notification.
"isCancel" (boolean): True if the notification was dismissed in the peer device.
"requestAnswer" (boolean): True if this is an answer to a "request" package.
Additionally the package can contain a payload with the icon of the notification
in PNG format.
The content of these fields is used to display the notifications to the user.
Note that if we receive a second notification with the same "id", we should
update the existent notification instead of creating a new one.
If the user dismisses a notification from this device, we have to request the
other device to remove it. This is done by sending a package with the fields
"id" set to the id of the notification we want to dismiss and a boolean "cancel"
set to true. The other device will answer with a notification package with
"isCancel" set to true when it is dismissed.
This simple plugin will just listen to "kdeconnect.telephony" like the telephony
plugin does. It reads the field "event", to see if it is "ringing" or "talking"
and then pauses all the music/video players reachable through MPRIS. When the
same kind of package is received but the boolean "isCancel" is set to true, it
will resume the playback of all the paused sources.
This plugin displays a notification to the user each time a package with type
"kdeconnect.ping" is received, regardless of the content.
......@@ -49,7 +49,7 @@ bool PingPlugin::receivePackage(const NetworkPackage& np)
notification->setPixmap(KIcon("dialog-ok").pixmap(48, 48));
notification->setComponentData(KComponentData("kdeconnect", "kdeconnect"));
notification->setTitle(device()->name());
notification->setText(np.get<QString>("message",i18n("Ping!")));
notification->setText(np.get<QString>("message",i18n("Ping!"))); //This can be a source of spam
notification->sendEvent();
return true;
......
This plugin will display a notification each time a package with type
"kdeconnect.telephony" is received. The type of notification will change
depending on the contents of the field "event" (string).
Valid contents for "event" are: "ringing", "talking", "missedCall" and "sms".
Note that "talking" is just ignored in this implementation, while the others
will display a system notification.
If the incoming package contains a "phoneNumber" string field, the notification
will also display it. Note that "phoneNumber" can be a contact name instead
of an actual phone number.
If the incoming package contains "isCancel" set to true, the package is ignored.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment