From a95886c4911f8538b53042149312727fb4a3839a Mon Sep 17 00:00:00 2001 From: John Freed Date: Mon, 11 Oct 2021 16:53:24 +0200 Subject: [PATCH] update DBus documentation (#773) --- man/signal-cli-dbus.5.adoc | 513 +++++++++++++++++++++++-------------- 1 file changed, 325 insertions(+), 188 deletions(-) diff --git a/man/signal-cli-dbus.5.adoc b/man/signal-cli-dbus.5.adoc index c5c27fa9..f38afc93 100755 --- a/man/signal-cli-dbus.5.adoc +++ b/man/signal-cli-dbus.5.adoc @@ -29,7 +29,7 @@ method(arg1, arg2, ...) -> return Where is according to DBus specification: -* : Array of ... (comma-separated list) +* : Array of ... (comma-separated list) (array:) * (...) : Struct (cannot be sent via `dbus-send`) * : Boolean (false|true) (boolean:) * : Signed 32-bit (int) integer (int32:) @@ -103,50 +103,191 @@ version() -> version:: Exceptions: None -=== Device methods -Requests for these methods are sent to a specific device (main or linked); the list is available -from the listDevices() method (see below under "Other methods"). +=== Group control methods +The following methods listen to the recipient's object path, which is constructed as follows: +"/org/asamk/Signal/" + DBusNumber +* DBusNumber : recipient's phone number, with underscore (_) replacing plus (+) -removeDevice() -> <>:: +createGroup(groupName, members, avatar) -> groupId:: +* groupName : String representing the display name of the group +* members : String array of new members to be invited to group +* avatar : Filename of avatar picture to be set for group (empty if none) +* groupId : Byte array representing the internal group identifier + +Exceptions: AttachmentInvalid, Failure, InvalidNumber; + +getGroup(groupId) -> objectPath:: +* groupId : Byte array representing the internal group identifier +* objectPath : DBusPath for the group + +getGroupMembers(groupId) -> members:: +* groupId : Byte array representing the internal group identifier +* members : String array with the phone numbers of all active members of a group + +Exceptions: None, if the group name is not found an empty array is returned + +joinGroup(inviteURI) -> <>:: +* inviteURI : String starting with https://signal.group/# + +If the link requires admin approval, this adds you to the requesting members list. Otherwise, this adds you to the pending members list. Exceptions: Failure -=== Other methods +listGroups() -> groups:: +* groups : Array of Structs(objectPath, groupId, groupName) +** objectPath : DBusPath +** groupId : Byte array representing the internal group identifier +** groupName : String representing the display name of the group -updateGroup(groupId, newName, members, avatar) -> groupId:: -* groupId : Byte array representing the internal group identifier -* newName : New name of group (empty if unchanged) -* members : String array of new members to be invited to group -* avatar : Filename of avatar picture to be set for group (empty if none) +sendGroupMessage(message, attachments, groupId) -> timestamp:: +* message : Text to send (can be UTF8) +* attachments : String array of filenames to send as attachments (passed as filename, so need to be readable by the user signal-cli is running under) +* groupId : Byte array representing the internal group identifier +* timestamp : Long, can be used to identify the corresponding Signal reply -Exceptions: AttachmentInvalid, Failure, InvalidNumber, GroupNotFound +Exceptions: GroupNotFound, Failure, AttachmentInvalid, InvalidGroupId -updateProfile(name, about, aboutEmoji , avatar, remove) -> <>:: -updateProfile(givenName, familyName, about, aboutEmoji , avatar, remove) -> <>:: -* name : Name for your own profile (empty if unchanged) -* givenName : Given name for your own profile (empty if unchanged) -* familyName : Family name for your own profile (empty if unchanged) -* about : About message for profile (empty if unchanged) -* aboutEmoji : Emoji for profile (empty if unchanged) -* avatar : Filename of avatar picture for profile (empty if unchanged) -* remove : Set to true if the existing avatar picture should be removed +sendGroupMessageReaction(emoji, remove, targetAuthor, targetSentTimestamp, groupId) -> timestamp:: +* emoji : Unicode grapheme cluster of the emoji +* remove : Boolean, whether a previously sent reaction (emoji) should be removed +* targetAuthor : String with the phone number of the author of the message to which to react +* targetSentTimestamp : Long representing timestamp of the message to which to react +* groupId : Byte array representing the internal group identifier +* timestamp : Long, can be used to identify the corresponding signal reply + +Exceptions: Failure, InvalidNumber, GroupNotFound, InvalidGroupId + +sendGroupRemoteDeleteMessage(targetSentTimestamp, groupId) -> timestamp:: +* targetSentTimestamp : Long representing timestamp of the message to delete +* groupId : Byte array with base64 encoded group identifier +* timestamp : Long, can be used to identify the corresponding signal reply + +Exceptions: Failure, GroupNotFound, InvalidGroupId + +=== Group methods +The following methods listen to the group's object path, which can be obtained from the listGroups() method and is constructed as follows: +"/org/asamk/Signal/" + DBusNumber + "/Groups/" + DBusGroupId +* DBusNumber : recipient's phone number, with underscore (_) replacing plus (+) +* DBusGroupId : groupId in base64 format, with underscore (_) replacing plus (+), equals (=), or slash (/) + +Groups have the following (case-sensitive) properties: +* Id (read-only) : Byte array representing the internal group identifier +* Name : Display name of the group +* Description : Description of the group +* Avatar (write-only) : Filename of the avatar +* IsBlocked : true=member will not receive group messages; false=not blocked +* IsMember (read-only) : always true (object path exists only for group members) +* IsAdmin (read-only) : true=member has admin privileges; false=not admin +* MessageExpirationTimer : int32 representing message expiration time for group +* Members (read-only) : String array of group members' phone numbers +* PendingMembers (read-only) : String array of pending members' phone numbers +* RequestingMembers (read-only) : String array of requesting members' phone numbers +* Admins (read-only) : String array of admins' phone numbers +* PermissionAddMember : String representing who has permission to add members +** ONLY_ADMINS, EVERY_MEMBER +* PermissionEditDetails : String representing who may edit group details +** ONLY_ADMINS, EVERY_MEMBER +* PermissionSendMessage : String representing who post messages to group +** ONLY_ADMINS, EVERY_MEMBER (note that ONLY_ADMINS is equivalent to IsAnnouncementGroup) +* GroupInviteLink (read-only) : String of the invitation link (starts with https://signal.group/#) + +To get a property, use (replacing `--session` with `--system` if needed): +`dbus-send --session --dest=org.asamk.Signal --print-reply $OBJECT_PATH org.freedesktop.DBus.Properties.Get string:org.asamk.Signal.Group string:$PROPERTY_NAME` + +To set a property, use: +`dbus-send --session --dest=org.asamk.Signal --print-reply $OBJECT_PATH org.freedesktop.DBus.Properties.Set string:org.asamk.Signal.Group string:$PROPERTY_NAME variant:$PROPERTY_TYPE:$PROPERTY_VALUE` + +To get all properties, use: +`dbus-send --session --dest=org.asamk.Signal --print-reply $OBJECT_PATH org.freedesktop.DBus.Properties.GetAll string:org.asamk.Signal.Group` + +addAdmins(recipients) -> <>:: +* recipients : String array of phone numbers + +Grant admit privileges to recipients. Exceptions: Failure +addMembers(recipients) -> <>:: +* recipients : String array of phone numbers -setExpirationTimer(number, expiration) -> <>:: -* number : Phone number of recipient -* expiration : int32 for the number of seconds before messages to this recipient disappear. Set to 0 to disable expiration. +Add recipients to group if they are pending members; otherwise add recipients to list of requesting members. -Exceptions: Failure, InvalidNumber +Exceptions: Failure -setContactBlocked(number, block) -> <>:: -* number : Phone number affected by method -* block : false=remove block, true=blocked +disableLink() -> <>:: -Messages from blocked numbers will no longer be forwarded via DBus. +Disables the group's invitation link. -Exceptions: InvalidNumber +Exceptions: Failure + +enableLink(requiresApproval) -> <>:: +* requiresApproval : true=add numbers using the link to the requesting members list + +Enables the group's invitation link. + +Exceptions: Failure + +quitGroup() -> <>:: +Exceptions: Failure, LastGroupAdmin + +removeAdmins(recipients) -> <>:: +* recipients : String array of phone numbers + +Remove admin privileges from recipients. + +Exceptions: Failure + +removeMembers(recipients) -> <>:: +* recipients : String array of phone numbers + +Remove recipients from group. + +Exceptions: Failure + +resetLink() -> <>:: + +Resets the group's invitation link to a new random URL starting with https://signal.group/# + +Exceptions: Failure + +=== Deprecated group control methods +The following deprecated methods listen to the recipient's object path, which is constructed as follows: +"/org/asamk/Signal/" + DBusNumber +* DBusNumber : recipient's phone number, with underscore (_) replacing plus (+) + +getGroupIds() -> groupList:: +groupList : Array of Byte arrays representing the internal group identifiers + +All groups known are returned, regardless of their active or blocked status. To query that use isMember() and isGroupBlocked() + +Exceptions: None + +getGroupName(groupId) -> groupName:: +* groupId : Byte array representing the internal group identifier +* groupName : The display name of the group + +Exceptions: None, if the group name is not found an empty string is returned + +isGroupBlocked(groupId) -> isGroupBlocked:: +* groupId : Byte array representing the internal group identifier +* isGroupBlocked : true=group is blocked; false=group is not blocked + +Dbus will not forward messages from a group when you have blocked it. + +Exceptions: InvalidGroupId, Failure + +isMember(groupId) -> isMember:: +* groupId : Byte array representing the internal group identifier +* isMember : true=you are a group member; false=you are not a group member + +Note that this method does not raise an Exception for a non-existing/unknown group but will simply return 0 (false) + +quitGroup(groupId) -> <>:: +* groupId : Byte array representing the internal group identifier + +Note that quitting a group will not remove the group from the getGroupIds command, but set it inactive which can be tested with isMember() + +Exceptions: GroupNotFound, Failure, InvalidGroupId setGroupBlocked(groupId, block) -> <>:: * groupId : Byte array representing the internal group identifier @@ -156,36 +297,35 @@ Messages from blocked groups will no longer be forwarded via DBus. Exceptions: GroupNotFound, InvalidGroupId -joinGroup(inviteURI) -> <>:: -* inviteURI : String starting with https://signal.group which is generated when you share a group link via Signal App +updateGroup(groupId, newName, members, avatar) -> groupId:: +* groupId : Byte array representing the internal group identifier +* newName : New name of group (empty if unchanged) +* members : String array of new members to be invited to group +* avatar : Filename of avatar picture to be set for group (empty if none) -Exceptions: Failure +Exceptions: AttachmentInvalid, Failure, InvalidNumber, GroupNotFound -quitGroup(groupId) -> <>:: -* groupId : Byte array representing the internal group identifier +=== Device control methods +The following methods listen to the recipient's object path, which is constructed as follows: +"/org/asamk/Signal/" + DBusNumber +* DBusNumber : recipient's phone number, with underscore (_) replacing plus (+) -Note that quitting a group will not remove the group from the getGroupIds command, but set it inactive which can be tested with isMember() +addDevice(deviceUri) -> <>:: +* deviceUri : URI in the form of "sgnl://linkdevice/?uuid=..." (formerly "tsdevice:/?uuid=...") Normally displayed by a Signal desktop app, smartphone app, or another signal-cli instance using the `link` control method. -Exceptions: GroupNotFound, Failure, InvalidGroupId +getDevice(deviceId) -> devicePath:: +* deviceId : Long representing a deviceId +* devicePath : DBusPath object for the device -isMember(groupId) -> isMember:: -* groupId : Byte array representing the internal group identifier -* isMember : true=you are a group member; false=you are not a group member +Exceptions: DeviceNotFound -Note that this method does not raise an Exception for a non-existing/unknown group but will simply return 0 (false) +listDevices() -> devices:: +* devices : Array of structs (objectPath, id, name) +** objectPath : DBusPath representing the device's object path +** id : Long representing the deviceId +** name : String representing the device's name -sendEndSessionMessage(recipients) -> <>:: -* recipients : Array of phone numbers - -Exceptions: Failure, InvalidNumber, UntrustedIdentity - -sendGroupMessage(message, attachments, groupId) -> timestamp:: -* message : Text to send (can be UTF8) -* attachments : String array of filenames to send as attachments (passed as filename, so need to be readable by the user signal-cli is running under) -* groupId : Byte array representing the internal group identifier -* timestamp : Long, can be used to identify the corresponding Signal reply - -Exceptions: GroupNotFound, Failure, AttachmentInvalid, InvalidGroupId +Exceptions: InvalidUri sendContacts() -> <>:: @@ -199,12 +339,89 @@ Sends a synchronization request to the primary device (for group, contacts, ...) Exceptions: Failure -sendNoteToSelfMessage(message, attachments) -> timestamp:: -* message : Text to send (can be UTF8) -* attachments : String array of filenames to send as attachments (passed as filename, so need to be readable by the user signal-cli is running under) -* timestamp : Long, can be used to identify the corresponding Signal reply +=== Device methods and properties +The following methods listen to the device's object path, which is constructed as follows: +"/org/asamk/Signal/" + DBusNumber + "/Devices/" + deviceId +* DBusNumber : recipient's phone number, with underscore (_) replacing plus (+) +* deviceId : Long representing the device identifier (obtained from listDevices() method) -Exceptions: Failure, AttachmentInvalid +Devices have the following (case-sensitive) properties: +* Id (read-only) : Long representing the device identifier +* Created (read-only) : Long representing the number of milliseconds since the Unix epoch +* LastSeen (read-only) : Long representing the number of milliseconds since the Unix epoch +* Name : String representing the display name of the device + +To get a property, use (replacing `--session` with `--system` if needed): +`dbus-send --session --dest=org.asamk.Signal --print-reply $OBJECT_PATH org.freedesktop.DBus.Properties.Get string:org.asamk.Signal.Device string:$PROPERTY_NAME` + +To set a property, use: +`dbus-send --session --dest=org.asamk.Signal --print-reply $OBJECT_PATH org.freedesktop.DBus.Properties.Set string:org.asamk.Signal.Device string:$PROPERTY_NAME variant:$PROPERTY_TYPE:$PROPERTY_VALUE` + +To get all properties, use: +`dbus-send --session --dest=org.asamk.Signal --print-reply $OBJECT_PATH org.freedesktop.DBus.Properties.GetAll string:org.asamk.Signal.Device` + +removeDevice() -> <>:: + +Exceptions: Failure + +=== Other methods + +getContactName(number) -> name:: +* number : Phone number +* name : Contact's name in local storage (from the master device for a linked account, or the one set with setContactName); if not set, contact's profile name is used + +Exceptions: None + +getContactNumber(name) -> numbers:: +* numbers : Array of phone number +* name : Contact or profile name ("firstname lastname") + +Searches contacts and known profiles for a given name and returns the list of all known numbers. May result in e.g. two entries if a contact and profile name is set. + +Exceptions: None + +getSelfNumber() -> number:: +* number : Your phone number + +Exceptions: None + +isContactBlocked(number) -> blocked:: +* number : Phone number +* blocked : true=blocked, false=not blocked + +For unknown numbers false is returned but no exception is raised. + +Exceptions: InvalidPhoneNumber + +isRegistered() -> result:: +isRegistered(number) -> result:: +isRegistered(numbers) -> results:: +* number : Phone number +* numbers : String array of phone numbers +* result : true=number is registered, false=number is not registered +* results : Boolean array of results + +For unknown numbers, false is returned, but no exception is raised. If no number is given, returns true (indicating that you are registered). + +Exceptions: InvalidNumber + +listNumbers() -> numbers:: +* numbers : String array of all known numbers + +This is a concatenated list of all defined contacts as well of profiles known (e.g. peer group members or sender of received messages) + +Exceptions: None + +removePin() -> <>:: + +Removes registration PIN protection. + +Exceptions: Failure + +sendEndSessionMessage(recipients) -> <>:: +* recipients : Array of phone numbers + +Exceptions: Failure, InvalidNumber, UntrustedIdentity sendMessage(message, attachments, recipient) -> timestamp:: sendMessage(message, attachments, recipients) -> timestamp:: @@ -218,28 +435,6 @@ Depending on the type of the recipient field this sends a message to one or mult Exceptions: AttachmentInvalid, Failure, InvalidNumber, UntrustedIdentity -sendTyping(recipient, stop) -> <>:: -* recipient : Phone number of a single recipient -* targetSentTimestamp : True, if typing state should be stopped - -Exceptions: Failure, GroupNotFound, UntrustedIdentity - -sendReadReceipt(recipient, targetSentTimestamps) -> <>:: -* recipient : Phone number of a single recipient -* targetSentTimestamps : Array of Longs to identify the corresponding Signal messages - -Exceptions: Failure, UntrustedIdentity - -sendGroupMessageReaction(emoji, remove, targetAuthor, targetSentTimestamp, groupId) -> timestamp:: -* emoji : Unicode grapheme cluster of the emoji -* remove : Boolean, whether a previously sent reaction (emoji) should be removed -* targetAuthor : String with the phone number of the author of the message to which to react -* targetSentTimestamp : Long representing timestamp of the message to which to react -* groupId : Byte array representing the internal group identifier -* timestamp : Long, can be used to identify the corresponding signal reply - -Exceptions: Failure, InvalidNumber, GroupNotFound, InvalidGroupId - sendMessageReaction(emoji, remove, targetAuthor, targetSentTimestamp, recipient) -> timestamp:: sendMessageReaction(emoji, remove, targetAuthor, targetSentTimestamp, recipients) -> timestamp:: * emoji : Unicode grapheme cluster of the emoji @@ -254,12 +449,18 @@ Depending on the type of the recipient(s) field this sends a reaction to one or Exceptions: Failure, InvalidNumber -sendGroupRemoteDeleteMessage(targetSentTimestamp, groupId) -> timestamp:: -* targetSentTimestamp : Long representing timestamp of the message to delete -* groupId : Byte array with base64 encoded group identifier -* timestamp : Long, can be used to identify the corresponding signal reply +sendNoteToSelfMessage(message, attachments) -> timestamp:: +* message : Text to send (can be UTF8) +* attachments : String array of filenames to send as attachments (passed as filename, so need to be readable by the user signal-cli is running under) +* timestamp : Long, can be used to identify the corresponding Signal reply -Exceptions: Failure, GroupNotFound, InvalidGroupId +Exceptions: Failure, AttachmentInvalid + +sendReadReceipt(recipient, targetSentTimestamps) -> <>:: +* recipient : Phone number of a single recipient +* targetSentTimestamps : Array of Longs to identify the corresponding Signal messages + +Exceptions: Failure, UntrustedIdentity sendRemoteDeleteMessage(targetSentTimestamp, recipient) -> timestamp:: sendRemoteDeleteMessage(targetSentTimestamp, recipients) -> timestamp:: @@ -272,11 +473,19 @@ Depending on the type of the recipient(s) field this deletes a message with one Exceptions: Failure, InvalidNumber -getContactName(number) -> name:: -* number : Phone number -* name : Contact's name in local storage (from the master device for a linked account, or the one set with setContactName); if not set, contact's profile name is used +sendTyping(recipient, stop) -> <>:: +* recipient : Phone number of a single recipient +* targetSentTimestamp : True, if typing state should be stopped -Exceptions: None +Exceptions: Failure, GroupNotFound, UntrustedIdentity + +setContactBlocked(number, block) -> <>:: +* number : Phone number affected by method +* block : false=remove block, true=blocked + +Messages from blocked numbers will no longer be forwarded via DBus. + +Exceptions: InvalidNumber setContactName(number,name<>) -> <>:: * number : Phone number @@ -284,61 +493,11 @@ setContactName(number,name<>) -> <>:: Exceptions: InvalidNumber, Failure -getGroupIds() -> groupList:: -groupList : Array of Byte arrays representing the internal group identifiers +setExpirationTimer(number, expiration) -> <>:: +* number : Phone number of recipient +* expiration : int32 for the number of seconds before messages to this recipient disappear. Set to 0 to disable expiration. -All groups known are returned, regardless of their active or blocked status. To query that use isMember() and isGroupBlocked() - -Exceptions: None - -getGroupName(groupId) -> groupName:: -* groupId : Byte array representing the internal group identifier -* groupName : The display name of the group - -Exceptions: None, if the group name is not found an empty string is returned - -getGroupMembers(groupId) -> members:: -* groupId : Byte array representing the internal group identifier -* members : String array with the phone numbers of all active members of a group - -Exceptions: None, if the group name is not found an empty array is returned - -listNumbers() -> numbers:: -* numbers : String array of all known numbers - -This is a concatenated list of all defined contacts as well of profiles known (e.g. peer group members or sender of received messages) - -Exceptions: None - -getContactNumber(name) -> numbers:: -* numbers : Array of phone number -* name : Contact or profile name ("firstname lastname") - -Searches contacts and known profiles for a given name and returns the list of all known numbers. May result in e.g. two entries if a contact and profile name is set. - -Exceptions: None - -isContactBlocked(number) -> blocked:: -* number : Phone number -* blocked : true=blocked, false=not blocked - -For unknown numbers false is returned but no exception is raised. - -Exceptions: InvalidPhoneNumber - -isGroupBlocked(groupId) -> isGroupBlocked:: -* groupId : Byte array representing the internal group identifier -* isGroupBlocked : true=group is blocked; false=group is not blocked - -Dbus will not forward messages from a group when you have blocked it. - -Exceptions: InvalidGroupId, Failure - -removePin() -> <>:: - -Removes registration PIN protection. - -Exceptions: Failure +Exceptions: Failure, InvalidNumber setPin(pin) -> <>:: * pin : PIN you set after registration (resets after 7 days of inactivity) @@ -347,51 +506,6 @@ Sets a registration lock PIN, to prevent others from registering your number. Exceptions: Failure -version() -> version:: -* version : Version string of signal-cli - -Exceptions: None - -getSelfNumber() -> number:: -* number : Your phone number - -Exceptions: None - -isRegistered() -> result:: -isRegistered(number) -> result:: -isRegistered(numbers) -> results:: -* number : Phone number -* numbers : String array of phone numbers -* result : true=number is registered, false=number is not registered -* results : Boolean array of results - -For unknown numbers, false is returned, but no exception is raised. If no number is given, returns true (indicating that you are registered). - -Exceptions: InvalidNumber - -addDevice(deviceUri) -> <>:: -* deviceUri : URI in the form of "sgnl://linkdevice/?uuid=..." (formerly "tsdevice:/?uuid=...") Normally displayed by a Signal desktop app, smartphone app, or another signal-cli instance using the `link` control method. - -listDevices() -> devices:: -* devices : Array of structs (objectPath, id, name) -** objectPath : DBusPath representing the device's object path -** id : Long representing the deviceId -** name : String representing the device's name - -Exceptions: InvalidUri - -getDevice(deviceId) -> devicePath:: -* deviceId : Long representing a (potential) deviceId -* devicePath : DBusPath object for the device - -Exceptions: DeviceNotFound - -uploadStickerPack(stickerPackPath) -> url:: -* stickerPackPath : Path to the manifest.json file or a zip file in the same directory -* url : URL of sticker pack after successful upload - -Exceptions: Failure - submitRateLimitChallenge(challenge, captcha) -> <>:: * challenge : The challenge token taken from the proof required error. * captcha : The captcha token from the solved captcha on the Signal website.. @@ -399,6 +513,29 @@ Can be used to lift some rate-limits by solving a captcha. Exception: IOErrorException +updateProfile(name, about, aboutEmoji , avatar, remove) -> <>:: +updateProfile(givenName, familyName, about, aboutEmoji , avatar, remove) -> <>:: +* name : Name for your own profile (empty if unchanged) +* givenName : Given name for your own profile (empty if unchanged) +* familyName : Family name for your own profile (empty if unchanged) +* about : About message for profile (empty if unchanged) +* aboutEmoji : Emoji for profile (empty if unchanged) +* avatar : Filename of avatar picture for profile (empty if unchanged) +* remove : Set to true if the existing avatar picture should be removed + +Exceptions: Failure + +uploadStickerPack(stickerPackPath) -> url:: +* stickerPackPath : Path to the manifest.json file or a zip file in the same directory +* url : URL of sticker pack after successful upload + +Exceptions: Failure + +version() -> version:: +* version : Version string of signal-cli + +Exceptions: None + == Signals SyncMessageReceived (timestamp, sender, destination, groupId, message, attachments):: * timestamp : Integer value that can be used to associate this e.g. with a sendMessage()