mir/kdeconnect-android
2
0
Fork 0
mirror of https://github.com/KDE/kdeconnect-android synced 2025-08-23 02:17:20 +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 * 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 * 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 * This comment is being written 30 August 2018. Distros will likely be running old versions for many years to come...
* many years to come...
* *
* @param messages Ordered list of parts of the message body which should be combined into a single message * @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 * Respond to a request for all conversations
* *
* * @param packet One packet of type [PACKET_TYPE_SMS_REQUEST_CONVERSATIONS] with the first message in all conversations that will be send
* Send one packet of type PACKET_TYPE_SMS_MESSAGE with the first message in all conversations
*/ */
@WorkerThread @WorkerThread
private fun handleRequestAllConversations(packet: NetworkPacket): Boolean { private fun handleRequestAllConversations(packet: NetworkPacket): Boolean {
@ -402,39 +400,36 @@ class SMSPlugin : Plugin() {
Manifest.permission.READ_PHONE_STATE, Manifest.permission.READ_PHONE_STATE,
) )
override val minSdk: Int
/** /**
* With versions older than KITKAT, lots of the content providers used in SMSHelper become * 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 * 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, * 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 * 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. * in [org.kde.kdeconnect.Device.onPacketReceived], it will not crash catastrophically.
* The onCreated method of this SMSPlugin complains if a version older than KitKat is loaded, * 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" * but it still allowed in the optimistic hope that things will "just work"
*/ */
get() { override val minSdk: Int = Build.VERSION_CODES.FROYO
return Build.VERSION_CODES.FROYO
}
companion object { companion object {
/** /**
* Packet used to indicate a batch of messages has been pushed from the remote device * 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 * The body should contain the key "messages" mapping to an array of messages
* *
*
* For example: * For example:
* ```
* { * {
* "version": 2 // This is the second version of this packet type and * "version": 2 // This is the second version of this packet type and
* // version 1 packets (which did not carry this flag) * // version 1 packets (which did not carry this flag)
* // are incompatible with the new format * // are incompatible with the new format
* "messages" : [ * "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 * // See constants declared in SMSHelper.Message for defined
* // values and explanations * // values and explanations
* "body" : "Hello", // Text message body * "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: * // The user's Address is excluded so:
* // If this is a single-target messsage, there will only be one * // If this is a single-target messsage, there will only be one
* // Address (the other party) * // Address (the other party)
@ -455,11 +450,11 @@ class SMSPlugin : Plugin() {
* The following optional fields of a message object may be defined * 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 * "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 * // 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 * // 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 * // 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: * An Attachment object looks like:
* { * {
@ -473,7 +468,7 @@ class SMSPlugin : Plugin() {
* { * {
* "address": <String> // Address (phone number, email address, etc.) of this object * "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 PACKET_TYPE_SMS_MESSAGE: String = "kdeconnect.sms.messages"
private const val SMS_MESSAGE_PACKET_VERSION: Int = 2 // We *send* packets of this version 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. * "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. * "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. * "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) * "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>, * "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) * "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 * "base64EncodedFile": <String> // Base64 encoded file
* "mimeType": <String> // File type (eg: image/jpg, video/mp4 etc.) * "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 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 * Packet sent to request the most-recent message in each conversations on the device
* *
*
* The request packet shall contain no body * The request packet shall contain no body
*/ */
private const val PACKET_TYPE_SMS_REQUEST_CONVERSATIONS: String = "kdeconnect.sms.request_conversations" 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 * Packet sent to request all the messages in a particular conversation
* *
*
* The following fields are available: * The following fields are available:
* "threadID": <long> // (Required) ThreadID to request * "threadID": <long> // (Required) ThreadID to request
* "rangeStartTimestamp": <long> // (Optional) Millisecond epoch timestamp indicating the start of the range from which to return messages * "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. * "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 * // May return fewer than expected if there are not enough or more than expected if many
* // messages have the same timestamp. * // messages have the same timestamp.
</long></long></long> */ */
private const val PACKET_TYPE_SMS_REQUEST_CONVERSATION: String = "kdeconnect.sms.request_conversation" 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: * The body should look like so:
* "part_id": <long> // Part id of the attachment * "part_id": <long> // Part id of the attachment
* "unique_identifier": <String> // This unique_identifier should come from a previous message packet's attachment field * "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" 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: * The following fields are available:
* "filename": <String> // Name of the attachment file in the database * "filename": <String> // Name of the attachment file in the database
* "payload": // Actual attachment file to be transferred * "payload": // Actual attachment file to be transferred
</String> */ */
private const val PACKET_TYPE_SMS_ATTACHMENT_FILE: String = "kdeconnect.sms.attachment_file" private const val PACKET_TYPE_SMS_ATTACHMENT_FILE: String = "kdeconnect.sms.attachment_file"
private const val KEY_PREF_BLOCKED_NUMBERS: String = "telephony_blocked_numbers" 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 * @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 { private fun constructBulkMessagePacket(messages: Iterable<SMSHelper.Message>): NetworkPacket {
val reply = NetworkPacket(PACKET_TYPE_SMS_MESSAGE) val reply = NetworkPacket(PACKET_TYPE_SMS_MESSAGE)