Implement Dbus setPin and removePin (#733)

[signal-cli] / man / signal-cli-dbus.5.adoc

diff --git a/man/signal-cli-dbus.5.adoc b/man/signal-cli-dbus.5.adoc
index 61091d4b18540fe899a6fc521bc88321595314b3..d562d06479b2871fc80f39bb0b9a23621e849b9b 100755 (executable)
--- a/man/signal-cli-dbus.5.adoc
+++ b/man/signal-cli-dbus.5.adoc
@@ -11,10 +11,11 @@ DBus API for signal-cli - A commandline and dbus interface for the Signal messen
 
 == Synopsis
 
 
 == Synopsis
 

-*signal-cli* [--config CONFIG] daemon --dbus-system
+*signal-cli* [--verbose] [--config CONFIG] [-u USERNAME] [-o {plain-text,json}] daemon [--system]

 
 

-*dbus-send* --system --type=method_call --print-reply --dest="org.asamk.Signal" /org/asamk/Signal org.asamk.Signal.<method> [string:<string argument>] [array:<type>:<array argument>]
+*dbus-send* [--system | --session] [--print-reply] --type=method_call --dest="org.asamk.Signal" /org/asamk/Signal[/_<phonenum>] org.asamk.Signal.<method> [string:<string argument>] [array:<type>:<array argument>]

 
 

+Note: when daemon was started without explicit `-u USERNAME`, the `dbus-send` command requires adding the phone number in `/org/asamk/Signal/_<phonenum>`.

 
 == Description
 
 
 == Description
 


@@ -32,6 +33,7 @@ Where <type> is according to DBus specification:
 * <ay>  : Byte Array
 * <aay> : Array of Byte Arrays
 * <as>  : String Array
 * <ay>  : Byte Array
 * <aay> : Array of Byte Arrays
 * <as>  : String Array

+* <ax>  : Array of signed 64 bit integer

 * <b>   : Boolean (0|1)
 * <x>   : Signed 64 bit integer
 * <>    : no return value
 * <b>   : Boolean (0|1)
 * <x>   : Signed 64 bit integer
 * <>    : no return value


@@ -54,7 +56,7 @@ updateProfile(newName<s>, about <s>, aboutEmoji <s>, avatar<s>, remove<b>) -> <>
 * newName     : New name for your own profile (empty if unchanged)
 * about       : About message for profile (empty if unchanged)
 * aboutEmoji  : Emoji for profile (empty if unchanged)
 * newName     : New 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 picutre for profile (empty if unchanged)
+* avatar      : Filename of avatar picture for profile (empty if unchanged)

 * remove      : Set to 1 if the existing avatar picture should be removed
 
 Exceptions: Failure
 * remove      : Set to 1 if the existing avatar picture should be removed
 
 Exceptions: Failure


@@ -90,14 +92,14 @@ Exceptions: GroupNotFound, Failure
 isMember(groupId<ay>) -> active<b>::
 * groupId : Byte array representing the internal group identifier
 
 isMember(groupId<ay>) -> active<b>::
 * groupId : Byte array representing the internal group identifier
 

-Note that this method 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)

 
 sendEndSessionMessage(recipients<as>) -> <>::
 * recipients : Array of phone numbers 
 
 Exceptions: Failure, InvalidNumber, UntrustedIdentity
 
 
 sendEndSessionMessage(recipients<as>) -> <>::
 * recipients : Array of phone numbers 
 
 Exceptions: Failure, InvalidNumber, UntrustedIdentity
 

-sendGroupMessage(message<s>, attachments<as>, groupId<a>) -> timestamp<x>::
+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


@@ -112,7 +114,7 @@ sendNoteToSelfMessage(message<s>, attachments<as>) -> timestamp<x>::
 
 Exceptions: Failure, AttachmentInvalid
 
 
 Exceptions: Failure, AttachmentInvalid
 

-sendMessage(message<s>, attachments<as>, recipient<s) -> timestamp<x>::
+sendMessage(message<s>, attachments<as>, recipient<s>) -> timestamp<x>::

 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)
 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)


@@ -122,11 +124,66 @@ sendMessage(message<s>, attachments<as>, recipients<as>) -> timestamp<x>::
 
 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.
 

-Expections: AttachmentInvalid, Failure, InvalidNumber, UntrustedIdentity
+Exceptions: AttachmentInvalid, Failure, InvalidNumber, UntrustedIdentity
+
+sendTyping(recipient<s>, stop<b>) -> <>::
+* recipient             : Phone number of a single recipient
+* targetSentTimestamp   : True, if typing state should be stopped
+
+Exceptions: Failure, GroupNotFound, UntrustedIdentity
+
+
+sendReadReceipt(recipient<s>, targetSentTimestamp<ax>) -> <>::
+* recipient             : Phone number of a single recipient
+* targetSentTimestamp   : Array of Longs to identify the corresponding signal messages
+
+Exceptions: Failure, UntrustedIdentity
+
+sendGroupMessageReaction(emoji<s>, remove<b>, targetAuthor<s>, targetSentTimestamp<x>, groupId<ay>) -> timestamp<x>::
+* 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 with base64 encoded group identifier
+* timestamp           : Long, can be used to identify the corresponding signal reply
+
+Exceptions: Failure, InvalidNumber, GroupNotFound
+
+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>::
+* 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
+* 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
+
+Depending on the type of the recipient(s) field this sends a reaction to one or multiple recipients.
+
+Exceptions: Failure, InvalidNumber
+
+sendGroupRemoteDeleteMessage(targetSentTimestamp<x>, groupId<ay>) -> timestamp<x>::
+* 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
+
+sendRemoteDeleteMessage(targetSentTimestamp<x>, recipient<s>) -> timestamp<x>::
+sendRemoteDeleteMessage(targetSentTimestamp<x>, recipients<as>) -> timestamp<x>::
+* targetSentTimestamp : Long representing timestamp of the message to delete
+* 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
+
+Depending on the type of the recipient(s) field this deletes a message with one or multiple recipients.
+
+Exceptions: Failure, InvalidNumber

 
 getContactName(number<s>) -> name<s>::
 * number  : Phone number
 
 getContactName(number<s>) -> name<s>::
 * number  : Phone number

-* name    : Name set in contacts (setContacts) or if not set the profile name 
+* 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

 
 setContactName(number<s>,name<>) -> <>::
 * number  : Phone number
 
 setContactName(number<s>,name<>) -> <>::
 * number  : Phone number


@@ -135,7 +192,7 @@ setContactName(number<s>,name<>) -> <>::
 getGroupIds() -> groupList<aay>::
 groupList : Array of Byte arrays representing the internal group identifiers
 
 getGroupIds() -> groupList<aay>::
 groupList : Array of Byte arrays representing the internal group identifiers
 

-All groups known are returned, regardsless of their active or blocked status. To query that use isMember() and isGroupBlocked()
+All groups known are returned, regardless of their active or blocked status. To query that use isMember() and isGroupBlocked()

 
 getGroupName(groupId<ay>) -> groupName<s>::
 groupName : The display name of the group 
 
 getGroupName(groupId<ay>) -> groupName<s>::
 groupName : The display name of the group 


@@ -158,7 +215,7 @@ getContactNumber(name<s>) -> numbers<as>::
 * numbers : Array of phone number
 * name    : Contact or profile name ("firstname lastname")
 
 * numbers : Array of phone number
 * name    : Contact or profile name ("firstname lastname")
 

-Searches contacts and know profiles for a given name and returns the list of all known names. May result in e.g. two entries if a contact and profile name is set.
+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
 
 isContactBlocked(number<s>) -> state<b>::
 * number  : Phone number


@@ -172,6 +229,19 @@ isGroupBlocked(groupId<ay>) -> state<b>::
 
 Exceptions: None, for unknown groups 0 (false) is returned
 
 
 Exceptions: None, for unknown groups 0 (false) is returned
 

+removePin() -> <>::
+
+Removes registration PIN protection.
+
+Exception: 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
+

 version() -> version<s>::
 * version : Version string of signal-cli
 
 version() -> version<s>::
 * version : Version string of signal-cli
 


@@ -198,6 +268,17 @@ MessageReceived(timestamp<x>, sender<s>, groupId<ay>, message<s>, attachments<as
 
 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
 

+== Examples
+
+Send a text message (without attachment) to a contact::
+dbus-send --print-reply --type=method_call --dest="org.asamk.Signal" /org/asamk/Signal org.asamk.Signal.sendMessage string:"Message text goes here" array:string: string:+123456789
+
+Send a group message::
+dbus-send --session --print-reply --type=method_call --dest=org.asamk.Signal /org/asamk/Signal org.asamk.Signal.sendGroupMessage  string:'The message goes here'  array:string:'/path/to/attachmnt1','/path/to/attachmnt2'  array:byte:139,22,72,247,116,32,170,104,205,164,207,21,248,77,185
+
+Print the group name corresponding to a groupId; the daemon runs on system bus, and was started without an explicit `-u USERNAME`::
+dbus-send --system --print-reply --type=method_call --dest='org.asamk.Signal' /org/asamk/Signal/_1234567890 org.asamk.Signal.getGroupName array:byte:139,22,72,247,116,32,170,104,205,164,207,21,248,77,185
+

 == Authors
 
 Maintained by AsamK <asamk@gmx.de>, who is assisted by other open source contributors.
 == Authors
 
 Maintained by AsamK <asamk@gmx.de>, who is assisted by other open source contributors.