mir/kdeconnect-android
2
0
Fork 0
mirror of https://github.com/KDE/kdeconnect-android synced 2025-08-22 09:58:08 +00:00
Code Issues Releases Wiki Activity

Improve SMSPlugin doc comment formatting

Browse Source
This commit is contained in:
TPJ Schikhof 2025-01-17 10:39:33 +01:00 committed by Albert Vaca Cintora
parent d73236ab96
commit fc18d8a10f
1 changed files with 66 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
src/org/kde/kdeconnect/Plugins/SMSPlugin/SMSPlugin.kt
View File

@ -174,8 +174,7 @@ class SMSPlugin : Plugin() {
* For backwards-compatibility with long-lived distro packages, this method needs to exist in
* order to support older desktop apps. However, note that it should no longer be used
*
* This comment is being written 30 August 2018. Distros will likely be running old versions for
* many years to come...
* This comment is being written 30 August 2018. Distros will likely be running old versions for many years to come...
*
* @param messages Ordered list of parts of the message body which should be combined into a single message
*/
@ -323,8 +322,7 @@ class SMSPlugin : Plugin() {
/**
* Respond to a request for all conversations
*
*
* Send one packet of type PACKET_TYPE_SMS_MESSAGE with the first message in all conversations
* @param packet One packet of type [PACKET_TYPE_SMS_REQUEST_CONVERSATIONS] with the first message in all conversations that will be send
*/
@WorkerThread
private fun handleRequestAllConversations(packet: NetworkPacket): Boolean {
@ -402,39 +400,36 @@ class SMSPlugin : Plugin() {
Manifest.permission.READ_PHONE_STATE,
)
override val minSdk: Int
/**
* With versions older than KITKAT, lots of the content providers used in SMSHelper become
* un-documented. Most manufacturers *did* do things the same way as was done in mainline
* Android at that time, but some did not. If the manufacturer followed the default route,
* everything will be fine. If not, the plugin will crash. But, since we have a global catch-all
* in Device.onPacketReceived, it will not crash catastrophically.
* The onCreated method of this SMSPlugin complains if a version older than KitKat is loaded,
* in [org.kde.kdeconnect.Device.onPacketReceived], it will not crash catastrophically.
* The [SMSPlugin.onCreate] method of this SMSPlugin complains if a version older than KitKat is loaded,
* but it still allowed in the optimistic hope that things will "just work"
*/
get() {
return Build.VERSION_CODES.FROYO
}
override val minSdk: Int = Build.VERSION_CODES.FROYO
companion object {
/**
* Packet used to indicate a batch of messages has been pushed from the remote device
*
*
* The body should contain the key "messages" mapping to an array of messages
*
*
* For example:
* ```
* {
* "version": 2 // This is the second version of this packet type and
* // version 1 packets (which did not carry this flag)
* // are incompatible with the new format
* "messages" : [
* { "event" : 1, // 32-bit field containing a bitwise-or of event flags
* {
* "event" : 1, // 32-bit field containing a bitwise-or of event flags
* // See constants declared in SMSHelper.Message for defined
* // values and explanations
* "body" : "Hello", // Text message body
* "addresses": <List></List><Address>> // List of Address objects, one for each participant of the conversation
* "addresses": <List<Address>> // List of Address objects, one for each participant of the conversation
* // The user's Address is excluded so:
* // If this is a single-target messsage, there will only be one
* // Address (the other party)
@ -455,11 +450,11 @@ class SMSPlugin : Plugin() {
* The following optional fields of a message object may be defined
* "sub_id": <int> // Android's subscriber ID, which is basically used to determine which SIM card the message
* // belongs to. This is mostly useful when attempting to reply to an SMS with the correct
* // SIM card using PACKET_TYPE_SMS_REQUEST.
* // SIM card using [PACKET_TYPE_SMS_REQUEST].
* // If this value is not defined or if it does not match a valid subscriber_id known by
* // Android, we will use whatever subscriber ID Android gives us as the default
*
* "attachments": <List></List><Attachment>> // List of Attachment objects, one for each attached file in the message.
* "attachments": <List<Attachment>> // List of Attachment objects, one for each attached file in the message.
*
* An Attachment object looks like:
* {
@ -473,7 +468,7 @@ class SMSPlugin : Plugin() {
* {
* "address": <String> // Address (phone number, email address, etc.) of this object
* }
</String></String></String></String></long></Attachment></int></Address> */
*/
private const val PACKET_TYPE_SMS_MESSAGE: String = "kdeconnect.sms.messages"
private const val SMS_MESSAGE_PACKET_VERSION: Int = 2 // We *send* packets of this version
@ -485,7 +480,7 @@ class SMSPlugin : Plugin() {
* "version": 2, // The version of the packet being sent. Compare to SMS_REQUEST_PACKET_VERSION before attempting to handle.
* "sendSms": true, // (Depreciated, ignored) Old versions of the desktop app used to mix phone calls, SMS, etc. in the same packet type and used this field to differentiate.
* "phoneNumber": "542904563213", // (Depreciated) Retained for backwards-compatibility. Old versions of the desktop app send a single phoneNumber. Use the Addresses field instead.
* "addresses": <List of Addresses>, // The one or many targets of this message
* "addresses": <List of Addresses> // The one or many targets of this message
* "messageBody": "Hi mom!", // Plain-text string to be sent as the body of the message (Optional if sending an attachment)
* "attachments": <List of Attached files>,
* "sub_id": 3859358340534 // Some magic number which tells Android which SIM card to use (Optional, if omitted, sends with the default SIM card)
@ -497,15 +492,15 @@ class SMSPlugin : Plugin() {
* "base64EncodedFile": <String> // Base64 encoded file
* "mimeType": <String> // File type (eg: image/jpg, video/mp4 etc.)
* }
</String></String></String></List></List> */
*/
private const val PACKET_TYPE_SMS_REQUEST: String = "kdeconnect.sms.request"
private const val SMS_REQUEST_PACKET_VERSION: Int =
2 // We *handle* packets of this version or lower. Update this number only if future packets break backwards-compatibility.
/** We *handle* packets of this version or lower. Update this number only if future packets break backwards-compatibility. **/
private const val SMS_REQUEST_PACKET_VERSION: Int = 2
/**
* Packet sent to request the most-recent message in each conversations on the device
*
*
* The request packet shall contain no body
*/
private const val PACKET_TYPE_SMS_REQUEST_CONVERSATIONS: String = "kdeconnect.sms.request_conversations"
@ -513,14 +508,13 @@ class SMSPlugin : Plugin() {
/**
* Packet sent to request all the messages in a particular conversation
*
*
* The following fields are available:
* "threadID": <long> // (Required) ThreadID to request
* "rangeStartTimestamp": <long> // (Optional) Millisecond epoch timestamp indicating the start of the range from which to return messages
* "numberToRequest": <long> // (Optional) Number of messages to return, starting from rangeStartTimestamp.
* // May return fewer than expected if there are not enough or more than expected if many
* // messages have the same timestamp.
</long></long></long> */
*/
private const val PACKET_TYPE_SMS_REQUEST_CONVERSATION: String = "kdeconnect.sms.request_conversation"
/**
@ -530,7 +524,7 @@ class SMSPlugin : Plugin() {
* The body should look like so:
* "part_id": <long> // Part id of the attachment
* "unique_identifier": <String> // This unique_identifier should come from a previous message packet's attachment field
</String></long> */
*/
private const val PACKET_TYPE_SMS_REQUEST_ATTACHMENT: String = "kdeconnect.sms.request_attachment"
/**
@ -540,16 +534,16 @@ class SMSPlugin : Plugin() {
* The following fields are available:
* "filename": <String> // Name of the attachment file in the database
* "payload": // Actual attachment file to be transferred
</String> */
*/
private const val PACKET_TYPE_SMS_ATTACHMENT_FILE: String = "kdeconnect.sms.attachment_file"
private const val KEY_PREF_BLOCKED_NUMBERS: String = "telephony_blocked_numbers"
/**
* Construct a proper packet of PACKET_TYPE_SMS_MESSAGE from the passed messages
* Construct a proper packet of [PACKET_TYPE_SMS_MESSAGE] from the passed messages
*
* @param messages Messages to include in the packet
* @return NetworkPacket of type PACKET_TYPE_SMS_MESSAGE
* @return NetworkPacket of type [PACKET_TYPE_SMS_MESSAGE]
*/
private fun constructBulkMessagePacket(messages: Iterable<SMSHelper.Message>): NetworkPacket {
val reply = NetworkPacket(PACKET_TYPE_SMS_MESSAGE)