Update documentation

man/signal-cli-dbus.5.adoc

@@ -63,7 +63,7 @@ can be captured by a Signal smartphone client. For example:
 
 `dbus-send --session --dest=org.asamk.Signal --type=method_call --print-reply /org/asamk/Signal org.asamk.Signal.link string:"My secondary client"|tr '\n' '\0'|sed 's/.*string //g'|sed 's/\"//g'|qrencode -s10 -tANSI256`
 
-Exception: Failure
+Exceptions: Failure
 
 listAccounts() -> accountList<as>::
 * accountList : Array of all attached accounts in DBus object path form
@@ -89,20 +89,28 @@ verify(number<s>, verificationCode<s>) -> <>::
 
 Command fails if PIN was set after previous registration; use verifyWithPin instead.
 
-Exception: Failure, InvalidNumber
+Exceptions: Failure, InvalidNumber
 
 verifyWithPin(number<s>, verificationCode<s>, pin<s>) -> <>::
 * number            : Phone number
 * verificationCode  : Code received from Signal after successful registration request
 * pin               : PIN you set with setPin command after verifying previous registration
 
-Exception: Failure, InvalidNumber
+Exceptions: Failure, InvalidNumber
 
 version() -> version<s>::
 * version : Version string of signal-cli
 
 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").
+
+removeDevice() -> <>::
+
+Exceptions: Failure
+
 === Other methods
 
 updateGroup(groupId<ay>, newName<s>, members<as>, avatar<s>) -> groupId<ay>::
@@ -130,11 +138,11 @@ setExpirationTimer(number<s>, expiration<i>) -> <>::
 * number     : Phone number of recipient
 * expiration : int32 for the number of seconds before messages to this recipient disappear. Set to 0 to disable expiration.
 
-Exceptions: Failure
+Exceptions: Failure, InvalidNumber
 
 setContactBlocked(number<s>, block<b>) -> <>::
 * number  : Phone number affected by method
-* block   : 0=remove block , 1=blocked
+* block   : false=remove block, true=blocked
 
 Messages from blocked numbers will no longer be forwarded via DBus.
 
@@ -142,11 +150,11 @@ Exceptions: InvalidNumber
 
 setGroupBlocked(groupId<ay>, block<b>) -> <>::
 * groupId : Byte array representing the internal group identifier
-* block   : 0=remove block , 1=blocked
+* block   : false=remove block , true=blocked
 
 Messages from blocked groups will no longer be forwarded via DBus.
 
-Exceptions: GroupNotFound
+Exceptions: GroupNotFound, InvalidGroupId
 
 joinGroup(inviteURI<s>) -> <>::
 * inviteURI : String starting with https://signal.group which is generated when you share a group link via Signal App
@@ -158,10 +166,11 @@ quitGroup(groupId<ay>) -> <>::
 
 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
+Exceptions: GroupNotFound, Failure, InvalidGroupId
 
-isMember(groupId<ay>) -> active<b>::
+isMember(groupId<ay>) -> isMember<b>::
 * 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)
 
@@ -174,9 +183,9 @@ sendGroupMessage(message<s>, attachments<as>, groupId<ay>) -> timestamp<x>::
 * 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   : Can be used to identify the corresponding signal reply
+* timestamp   : Long, can be used to identify the corresponding Signal reply
 
-Exceptions: GroupNotFound, Failure, AttachmentInvalid
+Exceptions: GroupNotFound, Failure, AttachmentInvalid, InvalidGroupId
 
 sendContacts() -> <>::
 
@@ -188,12 +197,12 @@ sendSyncRequest() -> <>::
 
 Sends a synchronization request to the primary device (for group, contacts, ...). Only works if sent from a secondary device.
 
-Exception: Failure
+Exceptions: Failure
 
 sendNoteToSelfMessage(message<s>, attachments<as>) -> timestamp<x>::
 * 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   : Can be used to identify the corresponding signal reply
+* timestamp   : Long, can be used to identify the corresponding Signal reply
 
 Exceptions: Failure, AttachmentInvalid
 
@@ -202,8 +211,8 @@ sendMessage(message<s>, attachments<as>, recipients<as>) -> timestamp<x>::
 * 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)
 * recipient   : Phone number of a single recipient
-* recipients  : Array of phone numbers 
+* recipients  : String array of phone numbers
-* timestamp   : Can be used to identify the corresponding signal reply
+* timestamp   : Long, can be used to identify the corresponding Signal reply
 
 Depending on the type of the recipient field this sends a message to one or multiple recipients.
 
@@ -215,10 +224,9 @@ sendTyping(recipient<s>, stop<b>) -> <>::
 
 Exceptions: Failure, GroupNotFound, UntrustedIdentity
 
-
+sendReadReceipt(recipient<s>, targetSentTimestamps<ax>) -> <>::
-sendReadReceipt(recipient<s>, targetSentTimestamp<ax>) -> <>::
 * recipient             : Phone number of a single recipient
-* targetSentTimestamp   : Array of Longs to identify the corresponding signal messages
+* targetSentTimestamps  : Array of Longs to identify the corresponding Signal messages
 
 Exceptions: Failure, UntrustedIdentity
 
@@ -227,10 +235,10 @@ sendGroupMessageReaction(emoji<s>, remove<b>, targetAuthor<s>, targetSentTimesta
 * 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 with base64 encoded group identifier
+* groupId             : Byte array representing the internal group identifier
 * timestamp           : Long, can be used to identify the corresponding signal reply
 
-Exceptions: Failure, InvalidNumber, GroupNotFound
+Exceptions: Failure, InvalidNumber, GroupNotFound, InvalidGroupId
 
 sendMessageReaction(emoji<s>, remove<b>, targetAuthor<s>, targetSentTimestamp<x>, recipient<s>) -> timestamp<x>::
 sendMessageReaction(emoji<s>, remove<b>, targetAuthor<s>, targetSentTimestamp<x>, recipients<as>) -> timestamp<x>::
@@ -240,7 +248,7 @@ sendMessageReaction(emoji<s>, remove<b>, targetAuthor<s>, targetSentTimestamp<x>
 * targetSentTimestamp : Long representing timestamp of the message to which to react
 * recipient           : String with the phone number of a single recipient
 * recipients          : Array of strings with phone numbers, should there be more recipients
-* timestamp           : Long, can be used to identify the corresponding signal reply
+* timestamp           : Long, can be used to identify the corresponding Signal reply
 
 Depending on the type of the recipient(s) field this sends a reaction to one or multiple recipients.
 
@@ -251,7 +259,7 @@ sendGroupRemoteDeleteMessage(targetSentTimestamp<x>, groupId<ay>) -> timestamp<x
 * groupId             : Byte array with base64 encoded group identifier
 * timestamp           : Long, can be used to identify the corresponding signal reply
 
-Exceptions: Failure, GroupNotFound
+Exceptions: Failure, GroupNotFound, InvalidGroupId
 
 sendRemoteDeleteMessage(targetSentTimestamp<x>, recipient<s>) -> timestamp<x>::
 sendRemoteDeleteMessage(targetSentTimestamp<x>, recipients<as>) -> timestamp<x>::
@@ -268,66 +276,87 @@ getContactName(number<s>) -> name<s>::
 * 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
+
 setContactName(number<s>,name<>) -> <>::
 * number  : Phone number
 * name    : Name to be set in contacts (in local storage with signal-cli)
 
+Exceptions: InvalidNumber, Failure
+
 getGroupIds() -> groupList<aay>::
 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<ay>) -> groupName<s>::
-groupName : The display name of the group 
+* groupId   : Byte array representing the internal group identifier
-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<ay>) -> members<as>::
-members   : String array with the phone numbers of all active members of a group
+* groupId   : Byte array representing the internal group identifier
-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<as>::
-numbers : String array of all known 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<s>) -> numbers<as>::
 * 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.
 
-isContactBlocked(number<s>) -> state<b>::
+Exceptions: None
+
+isContactBlocked(number<s>) -> blocked<b>::
 * number    : Phone number
-* state   : 1=blocked, 0=not blocked
+* blocked   : true=blocked, false=not blocked
 
-Exceptions: None, for unknown numbers 0 (false) is returned
+For unknown numbers false is returned but no exception is raised.
 
-isGroupBlocked(groupId<ay>) -> state<b>::
+Exceptions: InvalidPhoneNumber
+
+isGroupBlocked(groupId<ay>) -> isGroupBlocked<b>::
 * groupId        : Byte array representing the internal group identifier
-* state   : 1=blocked, 0=not blocked
+* isGroupBlocked : true=group is blocked; false=group is not blocked
 
-Exceptions: None, for unknown groups 0 (false) is returned
+Dbus will not forward messages from a group when you have blocked it.
+
+Exceptions: InvalidGroupId, Failure
 
 removePin() -> <>::
 
 Removes registration PIN protection.
 
-Exception: Failure
+Exceptions: Failure
 
 setPin(pin<s>) -> <>::
 * pin               : PIN you set after registration (resets after 7 days of inactivity)
 
 Sets a registration lock PIN, to prevent others from registering your number.
 
-Exception: Failure
+Exceptions: Failure
 
 version() -> version<s>::
 * version : Version string of signal-cli
 
+Exceptions: None
+
+getSelfNumber() -> number<s>::
+* number : Your phone number
+
+Exceptions: None
+
 isRegistered() -> result<b>::
 isRegistered(number<s>) -> result<b>::
 isRegistered(numbers<as>) -> results<ab>::
@@ -336,12 +365,12 @@ isRegistered(numbers<as>) -> results<ab>::
 * result  : true=number is registered, false=number is not registered
 * results : Boolean array of results
 
-Exception: InvalidNumber for an incorrectly formatted phone number. For unknown numbers, false is returned, but no exception is raised. If no number is given, returns whether you are registered (presumably true).
+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<s>) -> <>::
-* deviceUri : URI in the form of tsdevice:/?uuid=... Normally received from Signal desktop or smartphone app
+* deviceUri : URI in the form of tsdevice:/?uuid=... Normally displayed by a Signal desktop app, smartphone app, or another signal-cli instance using the `link` control method.
-
-Exception: InvalidUri
 
 listDevices() -> devices<a(oxs)>::
 * devices      : Array of structs (objectPath, id, name)
@@ -349,25 +378,19 @@ listDevices() -> devices<a(oxs)>::
 ** id           : Long representing the deviceId
 ** name         : String representing the device's name
 
-Exception: Failure
+Exceptions: InvalidUri
 
-removeDevice(deviceId<i>) -> <>::
+getDevice(deviceId<x>) -> devicePath<o>::
-* deviceId : Device ID to remove, obtained from listDevices() command
+* deviceId   : Long representing a (potential) deviceId
+* devicePath : DBusPath object for the device
 
-Exception: Failure
+Exceptions: DeviceNotFound
-
-updateDeviceName(deviceName<s>) -> <>::
-* deviceName : New name 
-
-Set a new name for this device (main or linked).
-
-Exception: Failure
 
 uploadStickerPack(stickerPackPath<s>) -> url<s>::
 * stickerPackPath : Path to the manifest.json file or a zip file in the same directory
 * url             : URL of sticker pack after successful upload
 
-Exception: Failure
+Exceptions: Failure
 
 submitRateLimitChallenge(challenge<s>, captcha<s>) -> <>::
 * challenge : The challenge token taken from the proof required error.
@@ -378,6 +401,13 @@ Exception: IOErrorException
 
 == Signals
 SyncMessageReceived (timestamp<x>, sender<s>, destination<s>, groupId<ay>, message<s>, attachments<as>)::
+* timestamp   : Integer value that can be used to associate this e.g. with a sendMessage()
+* sender      : Phone number of the sender
+* destination : DBus code for destination
+* groupId     : Byte array representing the internal group identifier (empty when private message)
+* message     : Message text
+* attachments : String array of filenames in the signal-cli storage (~/.local/share/signal-cli/attachments/)
+
 The sync message is received when the user sends a message from a linked device.
 
 ReceiptReceived (timestamp<x>, sender<s>)::
@@ -391,7 +421,7 @@ MessageReceived(timestamp<x>, sender<s>, groupId<ay>, message<s>, attachments<as
 * sender      : Phone number of the sender
 * groupId     : Byte array representing the internal group identifier (empty when private message)
 * message     : Message text
-* attachments : String array of filenames for the attachments. These files are located in the signal-cli storage and the current user needs to have read access there
+* attachments : String array of filenames in the signal-cli storage (~/.local/share/signal-cli/attachments/)
 
 This signal is received whenever we get a private message or a message is posted in a group we are an active member