From: John Freed Date: Tue, 21 Sep 2021 14:42:51 +0000 (+0200) Subject: Update documentation X-Git-Tag: v0.9.1~20 X-Git-Url: https://git.nmode.ca/signal-cli/commitdiff_plain/6501ffcdacc2ada63f30a00299d437d5aeff1293 Update documentation --- diff --git a/man/signal-cli-dbus.5.adoc b/man/signal-cli-dbus.5.adoc index 8168c421..3d977de6 100755 --- a/man/signal-cli-dbus.5.adoc +++ b/man/signal-cli-dbus.5.adoc @@ -48,9 +48,9 @@ Phone numbers always have the format + == 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:: @@ -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:: * accountList : Array of all attached accounts in DBus object path form @@ -89,20 +89,28 @@ verify(number, verificationCode) -> <>:: Command fails if PIN was set after previous registration; use verifyWithPin instead. -Exception: Failure, InvalidNumber +Exceptions: Failure, InvalidNumber verifyWithPin(number, verificationCode, pin) -> <>:: * 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:: * 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, newName, members, avatar) -> groupId:: @@ -130,11 +138,11 @@ 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. -Exceptions: Failure +Exceptions: Failure, InvalidNumber setContactBlocked(number, block) -> <>:: * 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, block) -> <>:: * 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) -> <>:: * 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) -> <>:: 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) -> active:: -* groupId : Byte array representing the internal group identifier +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) @@ -174,9 +183,9 @@ 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 : 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, 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 : 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, attachments, recipients) -> 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) * 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. @@ -215,10 +224,9 @@ sendTyping(recipient, stop) -> <>:: Exceptions: Failure, GroupNotFound, UntrustedIdentity - -sendReadReceipt(recipient, targetSentTimestamp) -> <>:: +sendReadReceipt(recipient, targetSentTimestamps) -> <>:: * 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, remove, targetAuthor, 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, remove, targetAuthor, targetSentTimestamp, recipient) -> timestamp:: sendMessageReaction(emoji, remove, targetAuthor, targetSentTimestamp, recipients) -> timestamp:: @@ -240,7 +248,7 @@ sendMessageReaction(emoji, remove, targetAuthor, targetSentTimestamp * 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, groupId) -> timestamp, recipient) -> timestamp:: sendRemoteDeleteMessage(targetSentTimestamp, recipients) -> timestamp:: @@ -268,66 +276,87 @@ 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 + setContactName(number,name<>) -> <>:: * number : Phone number * name : Name to be set in contacts (in local storage with signal-cli) +Exceptions: InvalidNumber, Failure + 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:: -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) -> members:: -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:: -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) -> 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. -isContactBlocked(number) -> state:: -* number : Phone number -* state : 1=blocked, 0=not blocked +Exceptions: None -Exceptions: None, for unknown numbers 0 (false) is returned +isContactBlocked(number) -> blocked:: +* number : Phone number +* blocked : true=blocked, false=not blocked -isGroupBlocked(groupId) -> state:: -* 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) -> isGroupBlocked:: +* 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. -Exception: Failure +Exceptions: Failure setPin(pin) -> <>:: * 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:: * version : Version string of signal-cli +Exceptions: None + +getSelfNumber() -> number:: +* number : Your phone number + +Exceptions: None + isRegistered() -> result:: isRegistered(number) -> result:: isRegistered(numbers) -> results:: @@ -336,12 +365,12 @@ isRegistered(numbers) -> 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) -> <>:: -* deviceUri : URI in the form of tsdevice:/?uuid=... Normally received from Signal desktop or smartphone app +Exceptions: InvalidNumber -Exception: InvalidUri +addDevice(deviceUri) -> <>:: +* 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:: * devices : Array of structs (objectPath, id, name) @@ -349,25 +378,19 @@ listDevices() -> devices:: ** id : Long representing the deviceId ** name : String representing the device's name -Exception: Failure - -removeDevice(deviceId) -> <>:: -* deviceId : Device ID to remove, obtained from listDevices() command - -Exception: Failure - -updateDeviceName(deviceName) -> <>:: -* deviceName : New name +Exceptions: InvalidUri -Set a new name for this device (main or linked). +getDevice(deviceId) -> devicePath:: +* deviceId : Long representing a (potential) deviceId +* devicePath : DBusPath object for the device -Exception: Failure +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 -Exception: Failure +Exceptions: Failure submitRateLimitChallenge(challenge, captcha) -> <>:: * 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 -SyncMessageReceived (timestamp, sender, destination, groupId,message, attachments):: +SyncMessageReceived (timestamp, sender, destination, groupId, message, attachments):: +* 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, sender):: @@ -391,7 +421,7 @@ MessageReceived(timestamp, sender, groupId, message, attachments