From 95ef31acea3892268e553b2a5f284412a4f954ee Mon Sep 17 00:00:00 2001 From: Albert Vaca Date: Tue, 24 Sep 2013 14:14:34 +0200 Subject: [PATCH] Documentation Added a README to each plugin explaining the content of the packages they send and receive Explained the format of encrypted packages. --- README | 28 ++++++++++++++++++--------- kded/plugins/battery/README | 17 ++++++++++++++++ kded/plugins/clipboard/README | 10 ++++++++++ kded/plugins/filetransfer/README | 11 +++++++++++ kded/plugins/mpriscontrol/README | 27 ++++++++++++++++++++++++++ kded/plugins/notifications/README | 32 +++++++++++++++++++++++++++++++ kded/plugins/pausemusic/README | 7 +++++++ kded/plugins/ping/README | 3 +++ kded/plugins/ping/pingplugin.cpp | 2 +- kded/plugins/telephony/README | 15 +++++++++++++++ 10 files changed, 142 insertions(+), 10 deletions(-) create mode 100644 kded/plugins/battery/README create mode 100644 kded/plugins/clipboard/README create mode 100644 kded/plugins/filetransfer/README create mode 100644 kded/plugins/mpriscontrol/README create mode 100644 kded/plugins/notifications/README create mode 100644 kded/plugins/pausemusic/README create mode 100644 kded/plugins/ping/README create mode 100644 kded/plugins/telephony/README diff --git a/README b/README index 0a4b2ec2c..eef0431a2 100644 --- a/README +++ b/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, - "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 diff --git a/kded/plugins/battery/README b/kded/plugins/battery/README new file mode 100644 index 000000000..b7f1ddde1 --- /dev/null +++ b/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 + + +Symmetrically, it sends its own battery information in packages with the same +format. + + +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. diff --git a/kded/plugins/clipboard/README b/kded/plugins/clipboard/README new file mode 100644 index 000000000..c9f50c299 --- /dev/null +++ b/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. diff --git a/kded/plugins/filetransfer/README b/kded/plugins/filetransfer/README new file mode 100644 index 000000000..817efc0d9 --- /dev/null +++ b/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. + + +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. + + diff --git a/kded/plugins/mpriscontrol/README b/kded/plugins/mpriscontrol/README new file mode 100644 index 000000000..d789f037b --- /dev/null +++ b/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. + diff --git a/kded/plugins/notifications/README b/kded/plugins/notifications/README new file mode 100644 index 000000000..fd49e5ae6 --- /dev/null +++ b/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. + diff --git a/kded/plugins/pausemusic/README b/kded/plugins/pausemusic/README new file mode 100644 index 000000000..81b414083 --- /dev/null +++ b/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. + diff --git a/kded/plugins/ping/README b/kded/plugins/ping/README new file mode 100644 index 000000000..b793c1e73 --- /dev/null +++ b/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. diff --git a/kded/plugins/ping/pingplugin.cpp b/kded/plugins/ping/pingplugin.cpp index 6bc7d3f6b..052d41fa3 100644 --- a/kded/plugins/ping/pingplugin.cpp +++ b/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("message",i18n("Ping!"))); + notification->setText(np.get("message",i18n("Ping!"))); //This can be a source of spam notification->sendEvent(); return true; diff --git a/kded/plugins/telephony/README b/kded/plugins/telephony/README new file mode 100644 index 000000000..4e1cacac3 --- /dev/null +++ b/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. +