Documentation

Added a README to each plugin explaining the content of the packages they
send and receive
Explained the format of encrypted packages.

README

@@ -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,
+  "id": 123456789,
-    "type": "org.kde.whatever",
+  "type": "org.kde.whatever",
-    "body": {
+  "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
+the emisor plugin and receiver plugin of this type of package need agree about
-its content.
+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

kded/plugins/battery/README

@@ -0,0 +1,17 @@
+
+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.

kded/plugins/clipboard/README

@@ -0,0 +1,10 @@
+
+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.

kded/plugins/filetransfer/README

@@ -0,0 +1,11 @@
+
+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>
+

kded/plugins/mpriscontrol/README

@@ -0,0 +1,27 @@
+
+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.
+

kded/plugins/notifications/README

@@ -0,0 +1,32 @@
+
+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.
+

kded/plugins/pausemusic/README

@@ -0,0 +1,7 @@
+
+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.
+

kded/plugins/ping/README

@@ -0,0 +1,3 @@
+
+This plugin displays a notification to the user each time a package with type
+"kdeconnect.ping" is received, regardless of the content.

kded/plugins/ping/pingplugin.cpp

@@ -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;

kded/plugins/telephony/README

@@ -0,0 +1,15 @@
+
+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.
+