Update documentation

diff --git a/man/signal-cli-dbus.5.adoc b/man/signal-cli-dbus.5.adoc
index 8168c421bf30b6b884abd22542bf138b6f7c0822..3d977de63bbfcd7226c3fec00259a5a9e6265f40 100755 (executable)
--- a/man/signal-cli-dbus.5.adoc
+++ b/man/signal-cli-dbus.5.adoc
@@ -48,9 +48,9 @@ Phone numbers always have the format +<countrycode><regional number>
 == Methods
 
 === Control methods
 == Methods
 
 === Control methods

-These methods are available if the daemon is started anonymously (without an explicit `-u USERNAME`). 
-Requests are sent to `/org/asamk/Signal`; requests related to individual accounts are sent to 
-`/org/asamk/Signal/_441234567890` where the + dialing code is replaced by an underscore (_). 
+These methods are available if the daemon is started anonymously (without an explicit `-u USERNAME`).
+Requests are sent to `/org/asamk/Signal`; requests related to individual accounts are sent to
+`/org/asamk/Signal/_441234567890` where the + dialing code is replaced by an underscore (_).

 Only `version()` is activated in single-user mode; the rest are disabled.
 
 link() -> deviceLinkUri<s>::
 Only `version()` is activated in single-user mode; the rest are disabled.
 
 link() -> deviceLinkUri<s>::


@@ -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`
 
 
 `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
 
 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.
 
 
 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
 
 
 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
 
 
 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>::
 === 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.
 
 * 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
 
 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.
 
 
 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
 
 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.
 
 
 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
 
 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()
 
 
 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>::
-* groupId : Byte array representing the internal group identifier
+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)
 
 
 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
 * 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() -> <>::
 
 
 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.
 
 
 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)
 
 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
 
 
 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
 * 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 
-* timestamp   : Can be used to identify the corresponding signal reply
+* recipients  : String array of phone numbers
+* 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.
 
 
 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
 
 
 Exceptions: Failure, GroupNotFound, UntrustedIdentity
 

-
-sendReadReceipt(recipient<s>, targetSentTimestamp<ax>) -> <>::
+sendReadReceipt(recipient<s>, targetSentTimestamps<ax>) -> <>::

 * recipient             : Phone number of a single recipient
 * 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
 
 
 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
 * 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
 
 * 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>::
 
 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
 * 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.
 
 
 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
 
 * 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>::
 
 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
 
 * 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)
 
 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()
 
 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>::
 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>::
 
 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>::
 
 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)
 
 
 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.
 
 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>::
-* number  : Phone number
-* state   : 1=blocked, 0=not blocked
+Exceptions: None

 
 

-Exceptions: None, for unknown numbers 0 (false) is returned
+isContactBlocked(number<s>) -> blocked<b>::
+* number    : Phone number
+* blocked   : true=blocked, false=not blocked

 
 

-isGroupBlocked(groupId<ay>) -> state<b>::
-* groupId : Byte array representing the internal group identifier
-* state   : 1=blocked, 0=not blocked
+For unknown numbers false is returned but no exception is raised.
+
+Exceptions: InvalidPhoneNumber
+
+isGroupBlocked(groupId<ay>) -> isGroupBlocked<b>::
+* groupId        : Byte array representing the internal group identifier
+* 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.
 
 
 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.
 
 
 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
 
 
 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>::
 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
 
 * 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).

 
 

-addDevice(deviceUri<s>) -> <>::
-* deviceUri : URI in the form of tsdevice:/?uuid=... Normally received from Signal desktop or smartphone app
+Exceptions: InvalidNumber

 
 

-Exception: InvalidUri
+addDevice(deviceUri<s>) -> <>::
+* 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.

 
 listDevices() -> devices<a(oxs)>::
 * devices      : Array of structs (objectPath, id, name)
 
 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
 
 ** id           : Long representing the deviceId
 ** name         : String representing the device's name
 

-Exception: Failure
-
-removeDevice(deviceId<i>) -> <>::
-* deviceId : Device ID to remove, obtained from listDevices() command
-
-Exception: Failure
-
-updateDeviceName(deviceName<s>) -> <>::
-* deviceName : New name 
+Exceptions: InvalidUri

 
 

-Set a new name for this device (main or linked).
+getDevice(deviceId<x>) -> devicePath<o>::
+* deviceId   : Long representing a (potential) deviceId
+* devicePath : DBusPath object for the device

 
 

-Exception: Failure
+Exceptions: DeviceNotFound

 
 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
 
 
 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.
 
 submitRateLimitChallenge(challenge<s>, captcha<s>) -> <>::
 * challenge : The challenge token taken from the proof required error.


@@ -377,7 +400,14 @@ Can be used to lift some rate-limits by solving a captcha.
 Exception: IOErrorException
 
 == Signals
 Exception: IOErrorException
 
 == Signals

-SyncMessageReceived (timestamp<x>, sender<s>, destination<s>, groupId<ay>,message<s>, attachments<as>)::
+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>)::
 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
 * 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
 
 
 This signal is received whenever we get a private message or a message is posted in a group we are an active member