nmode's Git Repositories - signal-cli/blob - man/signal-cli-dbus.5.adoc

   1 /////
   2 vim:set ts=4 sw=4 tw=82 noet:
   3 /////
   4 :quotes.~:
   5
   6 = signal-cli-dbus (5)
   7
   8 == Name
   9
  10 DBus API for signal-cli - A commandline and dbus interface for the Signal messenger
  11
  12 == Synopsis
  13
  14 *signal-cli* [--config CONFIG] daemon --dbus-system
  15
  16 *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>]
  17
  18
  19 == Description
  20
  21 See signal-cli (1) for details on the application.
  22
  23 This documentation handles the supported methods when running signal-cli as a DBus daemon.
  24
  25 The method are described as follows:
  26
  27 method(arg1<type>, arg2<type>, ...) -> return<type>
  28
  29 Where <type> is according to DBus specification:
  30
  31 * <s>   : String
  32 * <ay>  : Byte Array
  33 * <aay> : Array of Byte Arrays
  34 * <as>  : String Array
  35 * <b>   : Boolean (0|1)
  36 * <x>   : Signed 64 bit integer
  37 * <>    : no return value
  38
  39 Exceptions are the names of the Java Exceptions returned in the body field. They typically contain an additional message with details. All Exceptions begin with "org.asamk.Signal.Error." which is omitted here for better readability.
  40
  41 Phone numbers always have the format +<countrycode><regional number>
  42
  43 == Methods
  44
  45 updateGroup(groupId<ay>, newName<s>, members<as>, avatar<s>) -> groupId<ay>::
  46 * groupId  : Byte array representing the internal group identifier
  47 * newName  : New name of group (empty if unchanged)
  48 * members  : String array of new members to be invited to group
  49 * avatar   : Filename of avatar picture to be set for group (empty if none)
  50
  51 Exceptions: AttachmentInvalid, Failure, InvalidNumber, GroupNotFound
  52
  53 updateProfile(newName<s>, about <s>, aboutEmoji <s>, avatar<s>, remove<b>) -> <>::
  54 * newName     : New name for your own profile (empty if unchanged)
  55 * about       : About message for profile (empty if unchanged)
  56 * aboutEmoji  : Emoji for profile (empty if unchanged)
  57 * avatar      : Filename of avatar picutre for profile (empty if unchanged)
  58 * remove      : Set to 1 if the existing avatar picture should be removed
  59
  60 Exceptions: Failure
  61
  62 setContactBlocked(number<s>, block<b>) -> <>::
  63 * number  : Phone number affected by method
  64 * block   : 0=remove block , 1=blocked
  65
  66 Messages from blocked numbers will no longer be forwarded via DBus.
  67
  68 Exceptions: InvalidNumber
  69
  70 setGroupBlocked(groupId<ay>, block<b>) -> <>::
  71 * groupId : Byte array representing the internal group identifier
  72 * block   : 0=remove block , 1=blocked
  73
  74 Messages from blocked groups will no longer be forwarded via DBus.
  75
  76 Exceptions: GroupNotFound
  77
  78 joinGroup(inviteURI<s>) -> <>::
  79 * inviteURI : String starting with https://signal.group which is generated when you share a group link via Signal App
  80
  81 Exceptions: Failure
  82
  83 quitGroup(groupId<ay>) -> <>::
  84 * groupId : Byte array representing the internal group identifier
  85
  86 Note that quitting a group will not remove the group from the getGroupIds command, but set it inactive which can be tested with isMember()
  87
  88 Exceptions: GroupNotFound, Failure
  89
  90 isMember(groupId<ay>) -> active<b>::
  91 * groupId : Byte array representing the internal group identifier
  92
  93 Note that this method not raise an Exception for a non-existing/unknown group but will simply return 0 (false)
  94
  95 sendEndSessionMessage(recipients<as>) -> <>::
  96 * recipients : Array of phone numbers
  97
  98 Exceptions: Failure, InvalidNumber, UntrustedIdentity
  99
 100 sendGroupMessage(message<s>, attachments<as>, groupId<a>) -> timestamp<x>::
 101 * message     : Text to send (can be UTF8)
 102 * 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)
 103 * groupId     : Byte array representing the internal group identifier
 104 * timestamp   : Can be used to identify the corresponding signal reply
 105
 106 Exceptions: GroupNotFound, Failure, AttachmentInvalid
 107
 108 sendNoteToSelfMessage(message<s>, attachments<as>) -> timestamp<x>::
 109 * message     : Text to send (can be UTF8)
 110 * 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)
 111 * timestamp   : Can be used to identify the corresponding signal reply
 112
 113 Exceptions: Failure, AttachmentInvalid
 114
 115 sendMessage(message<s>, attachments<as>, recipient<s) -> timestamp<x>::
 116 sendMessage(message<s>, attachments<as>, recipients<as>) -> timestamp<x>::
 117 * message     : Text to send (can be UTF8)
 118 * 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)
 119 * recipient   : Phone number of a single recipient
 120 * recipients  : Array of phone numbers
 121 * timestamp   : Can be used to identify the corresponding signal reply
 122
 123 Depending on the type of the recipient field this sends a message to one or multiple recipients.
 124
 125 Expections: AttachmentInvalid, Failure, InvalidNumber, UntrustedIdentity
 126
 127 getContactName(number<s>) -> name<s>::
 128 * number  : Phone number
 129 * name    : Name set in contacts (setContacts) or if not set the profile name
 130
 131 setContactName(number<s>,name<>) -> <>::
 132 * number  : Phone number
 133 * name    : Name to be set in contacts (in local storage with signal-cli)
 134
 135 getGroupIds() -> groupList<aay>::
 136 groupList : Array of Byte arrays representing the internal group identifiers
 137
 138 All groups known are returned, regardsless of their active or blocked status. To query that use isMember() and isGroupBlocked()
 139
 140 getGroupName(groupId<ay>) -> groupName<s>::
 141 groupName : The display name of the group
 142 groupId   : Byte array representing the internal group identifier
 143
 144 Exceptions: None, if the group name is not found an empty string is returned
 145
 146 getGroupMembers(groupId<ay>) -> members<as>::
 147 members   : String array with the phone numbers of all active members of a group
 148 groupId   : Byte array representing the internal group identifier
 149
 150 Exceptions: None, if the group name is not found an empty array is returned
 151
 152 listNumbers() -> numbers<as>::
 153 numbers : String array of all known numbers
 154
 155 This is a concatenated list of all defined contacts as well of profiles known (e.g. peer group members or sender of received messages)
 156
 157 getContactNumber(name<s>) -> numbers<as>::
 158 * numbers : Array of phone number
 159 * name    : Contact or profile name ("firstname lastname")
 160
 161 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.
 162
 163 isContactBlocked(number<s>) -> state<b>::
 164 * number  : Phone number
 165 * state   : 1=blocked, 0=not blocked
 166
 167 Exceptions: None, for unknown numbers 0 (false) is returned
 168
 169 isGroupBlocked(groupId<ay>) -> state<b>::
 170 * groupId : Byte array representing the internal group identifier
 171 * state   : 1=blocked, 0=not blocked
 172
 173 Exceptions: None, for unknown groups 0 (false) is returned
 174
 175 version() -> version<s>::
 176 * version : Version string of signal-cli
 177
 178 isRegistred -> result<b>::
 179 * result : Currently always returns 1=true
 180
 181 == Signals
 182
 183 SyncMessageReceived (timestamp<x>, sender<s>, destination<s>, groupId<ay>,message<s>, attachments<as>)::
 184 The sync message is received when the user sends a message from a linked device.
 185
 186 ReceiptReceived (timestamp<x>, sender<s>)::
 187 * timestamp : Integer value that can be used to associate this e.g. with a sendMessage()
 188 * sender    : Phone number of the sender
 189
 190 This signal is sent by each recipient (e.g. each group member) after the message was successfully delivered to the device
 191
 192 MessageReceived(timestamp<x>, sender<s>, groupId<ay>, message<s>, attachments<as>)::
 193 * timestamp   : Integer value that is used by the system to send a ReceiptReceived reply
 194 * sender      : Phone number of the sender
 195 * groupId     : Byte array representing the internal group identifier (empty when private message)
 196 * message     : Message text
 197 * 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
 198
 199 This signal is received whenever we get a private message or a message is posted in a group we are an active member
 200
 201 == Authors
 202
 203 Maintained by AsamK <asamk@gmx.de>, who is assisted by other open source contributors.
 204 For more information about signal-cli development, see
 205 <https://github.com/AsamK/signal-cli>.