Bridge API

De Goffiwiki
Aller à : navigation, rechercher


Overview

This is an autogenerated doc for SàT bridge's API

Signals

actionNew

A frontend action is requested


category core
signature a{ss}sis
parameters
action_data
a dict where key can be:
- xmlui: a XMLUI need to be displayed
- progress: a progress id
- meta_*: meta information on the action, used to make automation more easy,
some are defined below
- meta_from_jid: origin of the request
- meta_type: type of the request, can be one of:
- C.META_TYPE_FILE: a file transfer request validation
- C.META_TYPE_OVERWRITE: a file overwriting confirmation
- meta_progress_id: progress id linked to this action
id
action id
This id can be used later by frontends to announce to other ones that the action is managed and can now be ignored.
security_limit
-1 means no security, 0 is the maximum security then the higher the less secure
profile
Name of the profile.

connected

Connection is done


category core
signature ss
parameters
profile
Name of the profile.
jid_s
the JID that we were assigned by the server, as the resource might differ from the JID we asked for.

contactDeleted

A contact has been supressed from roster


category core
signature ss
parameters
entity_jid
JID of the contact removed from roster
profile
Name of the profile.

disconnected

Connection is finished or lost


category core
signature s
parameters
profile
Name of the profile.

entityDataUpdated

An entity's data has been updated


category core
signature ssss
parameters
jid
entity's bare jid
name
Name of the updated value
value
New value
profile
Name of the profile.

messageNew

A message has been received


category core
signature sdssa{ss}a{ss}sa{ss}s
parameters
uid
unique ID of the message (id specific to SàT, this it *NOT* an XMPP id)
timestamp
when the message was sent (or declared sent for delayed messages)
from_jid
JID where the message is comming from
to_jid
JID where the message must be sent
message
message itself, can be in several languages (key is language code or for default)
subject
subject of the message, can be in several languages (key is language code or for default)
mess_type
Type of the message (cf RFC 6121 §5.2.2) + C.MESS_TYPE_INFO (system info)
extra
extra message information, can have data added by plugins and/or:
- thread: id of the thread
- thread_parent: id of the parent of the current thread
- received_timestamp: date of receiption for delayed messages
- delay_sender: entity which has originally sent or which has delayed the message
- info_type: subtype for info messages
profile
Name of the profile.

newContact

New contact received in roster


category core
signature sa{ss}ass
parameters
contact_jid
JID which has just been added
attributes
Dictionary of attributes where keys are:
- name: name of the contact
- to: "True" if the contact give its presence information to us
- from: "True" if contact is registred to our presence information
- ask: "True" is subscription is pending
groups
Roster's groups where the contact is
profile
Name of the profile.

paramUpdate

A parameter has been changed


category core
signature ssss
parameters
name
Name of the updated parameter
value
New value of the parameter
category
Category of the updated parameter
profile
Name of the profile.

presenceUpdate

Somebody changed his presence information.


category core
signature ssia{ss}s
parameters
entity_jid
JID from which we have presence informatios
show
availability status (see RFC 6121 §4.7.2.1)
priority
Priority level of the ressource (see RFC 6121 §4.7.2.3)
statuses
Natural language description of the availability status (see RFC 6121 §4.7.2.2)
profile
Name of the profile.

progressError

There was an error during progressing operation


category core
signature sss
parameters
id
id of the progression operation
error
error message
profile
Name of the profile.

progressFinished

A progressing operation is finished


category core
signature sa{ss}s
parameters
id
id of the progression operation
metadata
dict of progress status metadata, key can be:
- hash: value of the computed hash
- hash_algo: alrorithm used to compute hash
- hash_verified: C.BOOL_TRUE if hash is verified and OK
C.BOOL_FALSE if hash was not received (progressError will be used if there is a mismatch)
- url: url linked to the progression (e.g. download url after a file upload)
profile
Name of the profile.

progressStarted

A progressing operation has just started


category core
signature sa{ss}s
parameters
id
id of the progression operation
metadata
dict of progress metadata, key can be:
- name: name of the progression, full path for a file
- direction: "in" for incoming data, "out" else
- type: type of the progression:
C.META_TYPE_FILE: file transfer
profile
Name of the profile.

subscribe

Somebody wants to be added in roster


category core
signature sss
parameters
sub_type
Subscription states (see RFC 6121 §3)
entity_jid
JID from which the subscription is coming
profile
Name of the profile.

Methods

actionsGet

Get all not yet answered actions


category core
signature in s
signature out a(a{ss}si)
parameters
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
DEFAULT: "@DEFAULT@"
return value

list of data as for actionNew (without the profile)

addContact

Add a contact to profile's roster


category core
signature in ss
signature out
parameters
entity_jid
JID to add to roster
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
DEFAULT: "@DEFAULT@"

asyncDeleteProfile

Delete a profile


This method is asynchronous

category core
signature in s
signature out
parameters
profile
Name of the profile.
return value

callback is called when profile has been deleted from database and memory

asyncGetParamA

Helper method to get a parameter's attribute


This method is asynchronous

category core
signature in sssis
signature out s
parameters
name
as for setParam
category
as for setParam
attribute
Name of the attribute
DEFAULT: "value"
security_limit
-1 means no security, 0 is the maximum security then the higher the less secure
DEFAULT: -1
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
DEFAULT: "@DEFAULT@"

asyncGetParamsValuesFromCategory

Get "attribute" for all params of a category


This method is asynchronous

category code
signature in sis
signature out a{ss}
parameters
category
as for setParam
security_limit
-1 means no security, 0 is the maximum security then the higher the less secure
DEFAULT: -1
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
DEFAULT: "@DEFAULT@"

connect

Connect a profile


This method is asynchronous

category core
signature in ssa{ss}
signature out b
parameters
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
DEFAULT: "@DEFAULT@"
password
the SàT profile password
DEFAULT: ''
options
connection options
DEFAULT: {}
return value

a deferred boolean or failure:
- boolean if the profile authentication succeed:
- True if the XMPP connection was already established
- False if the XMPP connection has been initiated (it may still fail)
- failure if the profile authentication failed

delContact

Remove a contact from profile's roster


This method is asynchronous

category core
signature in ss
signature out
parameters
entity_jid
JID to remove from roster
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
DEFAULT: "@DEFAULT@"

discoFindByFeatures

Discover items of an entity


This method is asynchronous

category core
signature in asa(ss)bbbbbs
signature out (a{sa(sss)}a{sa(sss)}a{sa(sss)})
parameters
namespaces
namespaces of the features to check
identities
identities to filter
bare_jid
if True only retrieve bare jids
if False, retrieve full jids of connected resources
DEFAULT: False
service
True to check server's services
DEFAULT: True
roster
True to check connected devices from people in roster
DEFAULT: True
own_jid
True to check profile's jid
DEFAULT: True
local_device
True to check device on which the backend is running
DEFAULT: False
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
DEFAULT: u"@DEFAULT@"
return value

tuple of maps of found entities full jids to their identities. Maps are in this order:
- services entities
- own entities (i.e. entities linked to profile's jid)
- roster entities

discoInfos

Discover infos on an entity


This method is asynchronous

category core
signature in ssbs
signature out (asa(sss)a{sa(a{ss}as)})
parameters
entity_jid
JID to discover
node
node to use
DEFAULT: u''
use_cache
use cached data if available
DEFAULT: True
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
DEFAULT: u"@DEFAULT@"
return value

discovery data:
- list of features
- list of identities (category, type, name)
- dictionary of extensions (FORM_TYPE as key), with value of:
- list of field which are:
- dictionary key/value where key can be:

  • var
  • label
  • type
  • desc

- list of values

discoItems

Discover items of an entity


This method is asynchronous

category core
signature in ssbs
signature out a(sss)
parameters
entity_jid
JID to discover
node
node to use
DEFAULT: u''
use_cache
use cached data if available
DEFAULT: True
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
DEFAULT: u"@DEFAULT@"
return value

array of tuple (entity, node identifier, name)

disconnect

Disconnect a profile


This method is asynchronous

category core
signature in s
signature out
parameters
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
DEFAULT: "@DEFAULT@"

getConfig

get main configuration option


category core
signature in ss
signature out s
parameters
section
section of the configuration file (empty string for DEFAULT)
name
name of the option

getContacts

Return information about all contacts (the roster)


This method is asynchronous

category core
signature in s
signature out a(sa{ss}as)
parameters
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
DEFAULT: "@DEFAULT@"
return value

array of tuples with the following values:
- JID of the contact
- list of attributes as in newContact
- groups where the contact is

getContactsFromGroup

Return information about all contacts


category core
signature in ss
signature out as
parameters
group
name of the group to check
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
DEFAULT: "@DEFAULT@"
return value

array of jids

getEntitiesData

Get data in cache for several entities at once


category core
signature in asass
signature out a{sa{ss}}
parameters
jids
list of entities bare jid, or empty list to have all jids in cache
keys
list of keys to get
profile
Name of the profile.
return value

dictionary with jids as keys and dictionary of asked key as values
if key doesn't exist for a jid, the resulting dictionary will not have it

getEntityData

Get data in cache for an entity


category core
signature in sass
signature out a{ss}
parameters
jid
entity's bare jid
keys
list of keys to get
profile
Name of the profile.
return value

dictionary of asked key,
if key doesn't exist, the resulting dictionary will not have the key

getFeatures

Get available features and plugins features can changes for differents profiles, e.g. because of differents server capabilities


This method is asynchronous

category core
signature in s
signature out a{sa{ss}}
parameters
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
return value

dictionary of available features:
plugin import name is used as key, data is an other dict managed by the plugin

getMainResource

Return the last resource connected for a contact


category core
signature in ss
signature out s
parameters
contact_jid
jid of the contact
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
DEFAULT: "@DEFAULT@"
return value

the resource connected of the contact with highest priority, or ""

getParamA

Helper method to get a parameter's attribute *when profile is connected*


category core
signature in ssss
signature out s
parameters
name
as for setParam
category
as for setParam
attribute
Name of the attribute
DEFAULT: "value"
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
DEFAULT: "@DEFAULT@"

getParamsCategories

Get all categories currently existing in parameters


category core
signature in
signature out as
parameters
return value

list of categories

getParamsUI

Return a SàT XMLUI for parameters, eventually restrict the result to the parameters concerning a given frontend


This method is asynchronous

category core
signature in iss
signature out s
parameters
security_limit
-1 means no security, 0 is the maximum security then the higher the less secure
DEFAULT: -1
app
name of the frontend requesting the parameters, or to get all parameters
DEFAULT: ''
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
DEFAULT: "@DEFAULT@"

getPresenceStatuses

Return presence information of all contacts


category core
signature in s
signature out a{sa{s(sia{ss})}}
parameters
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
DEFAULT: "@DEFAULT@"
return value

Dict of presence with bare JID of contact as key, and value as follow:
A dict where key is the resource and the value is a tuple with (show, priority, statuses) as for presenceUpdate

getReady

Return when backend is initialised


This method is asynchronous

category core
signature in
signature out
parameters

getVersion

Get "Salut à Toi" full version


category core
signature in
signature out s
parameters

getWaitingSub

Get subscription requests in queue


category core
signature in s
signature out a{ss}
parameters
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
DEFAULT: "@DEFAULT@"
return value

Dict where contact JID is the key, and value is the subscription type

historyGet

Get history of a communication between two entities


This method is asynchronous

category core
signature in ssiba{ss}s
signature out a(sdssa{ss}a{ss}sa{ss})
parameters
from_jid
source JID (bare jid for catch all, full jid else)
to_jid
dest JID (bare jid for catch all, full jid else)
limit
max number of history elements to get (0 for the whole history)
between
True if we want history between the two jids (in both direction), False if we only want messages from from_jid to to_jid
DEFAULT: True
filters
patterns to filter the history results, can be:
- body: pattern must be in message body
- search: pattern must be in message body or source resource
- types: type must one of those, values are separated by spaces
- not_types: type must not be one of those, values are separated by spaces
DEFAULT: ''
profile
Name of the profile.
DEFAULT: "@NONE@"
return value

Ordered list (by timestamp) of data as in messageNew (without final profile)

isConnected

Tell if a profile is connected


category core
signature in s
signature out b
parameters
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
DEFAULT: "@DEFAULT@"

launchAction

Launch a registred action


This method is asynchronous

category core
signature in sa{ss}s
signature out a{ss}
parameters
callback_id
id of the registred callback
data
optional data
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
DEFAULT: "@DEFAULT@"
return value

dict where key can be:
- xmlui: a XMLUI need to be displayed

loadParamsTemplate

Load parameters template from xml file


category core
signature in s
signature out b
parameters
filename
input filename
return value

boolean (True in case of success)

menuHelpGet

Get help information for a menu


category core
signature in ss
signature out s
parameters
menu_id
id of the menu (same as callback_id)
language
language in which the menu should be translated (empty string for default)
return value

Translated help string

menuLaunch

Launch a registred menu


This method is asynchronous

category core
signature in sasa{ss}is
signature out a{ss}
parameters
menu_type
type of the menu (C.MENU_*)
path
canonical (untranslated) path of the menu
data
optional data
security_limit
-1 means no security, 0 is the maximum security then the higher the less secure
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
return value

dict where key can be:
- xmlui: a XMLUI need to be displayed

menusGet

Get all additional menus


category core
signature in si
signature out a(ssasasa{ss})
parameters
language
language in which the menu should be translated (empty string for default)
security_limit
security_limit: -1 means no security, 0 is the maximum security then the higher the less secure
return value

list of tuple with the following value:
- menu_id: menu id (same as callback id)
- menu_type: Type which can be:

  • NORMAL: Classical application menu

- menu_path: raw path of the menu
- menu_path_i18n: translated path of the menu
- extra: extra data, like icon name

messageSend

Send a message


This method is asynchronous

category core
signature in sa{ss}a{ss}sa{ss}s
signature out
parameters
to_jid
JID of the recipient
message
body of the message:
key is the language of the body, use when unknown
subject
Subject of the message
key is the language of the subject, use when unknown
DEFAULT: {}
mess_type
Type of the message (cf RFC 6121 §5.2.2) or "auto" for automatic type detection
DEFAULT: "auto"
extra
optional data that can be used by a plugin to build more specific messages
DEFAULT: {}
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
DEFAULT: "@NONE@"

namespacesGet

Get a dict to short name => whole namespaces


category core
signature in
signature out a{ss}
parameters
return value

namespaces mapping

paramsRegisterApp

Register frontend's specific parameters


category core
signature in sis
signature out
parameters
xml
XML definition of the parameters to be added
security_limit
-1 means no security, 0 is the maximum security then the higher the less secure
DEFAULT: -1
app
name of the frontend registering the parameters
DEFAULT: ''

profileCreate

Create a new profile


This method is asynchronous

category core
signature in sss
signature out
parameters
profile
Name of the profile.
password
password of the profile
DEFAULT: ''
component
set to component entry point if it is a component, else use empty string
DEFAULT: ''
return value

callback is called when profile actually exists in database and memory

profileIsSessionStarted

Tell if a profile session is loaded


category core
signature in s
signature out b
parameters
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
DEFAULT: "@DEFAULT@"

profileNameGet

Get real profile name from profile key


category core
signature in s
signature out s
parameters
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
DEFAULT: "@DEFAULT@"
return value

Real profile name

profileSetDefault

Set default profile


category core
signature in s
signature out
parameters
profile
Name of the profile.

profileStartSession

Start a profile session without connecting it (if it's not already the case)


This method is asynchronous

category core
signature in ss
signature out b
parameters
password
the SàT profile password
DEFAULT: ''
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
DEFAULT: "@DEFAULT@"
return value

D(bool):
- True if the profile session was already started
- False else

profilesListGet

Get list of profiles


category core
signature in bb
signature out as
parameters
clients
get clients profiles
DEFAULT: True
components
get components profiles
DEFAULT: False

progressGet

Get progress information for an action


category core
signature in ss
signature out a{ss}
parameters
id
id of the progression status
profile
Name of the profile.
return value

dict with progress informations:
- position: current position
- size: end position (optional if not known)
other metadata may be present

progressGetAll

Get all active progress informations


category core
signature in s
signature out a{sa{sa{ss}}}
parameters
profile
Name of the profile. or C.PROF_KEY_ALL for all profiles
return value

a dict which map profile to progress_dict
progress_dict map progress_id to progress_data
progress_data is the same dict as returned by progressGet

progressGetAllMetadata

Get all active progress informations


category core
signature in s
signature out a{sa{sa{ss}}}
parameters
profile
Name of the profile. or C.PROF_KEY_ALL for all profiles
return value

a dict which map profile to progress_dict
progress_dict map progress_id to progress_metadata
progress_metadata is the same dict as sent by progressStarted

saveParamsTemplate

Save parameters template to xml file


category core
signature in s
signature out b
parameters
filename
output filename
return value

boolean (True in case of success)

sessionInfosGet

Get various informations on current profile session


This method is asynchronous

category core
signature in s
signature out a{ss}
parameters
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
return value

session informations, with at least the following keys:
jid: current full jid
started: date of creation of the session (Epoch time)

setParam

Change a parameter


category core
signature in sssis
signature out
parameters
name
Name of the parameter to change
value
New Value of the parameter
category
Category of the parameter to change
security_limit
-1 means no security, 0 is the maximum security then the higher the less secure
DEFAULT: -1
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
DEFAULT: "@DEFAULT@"

setPresence

Set presence information for the profile


category core
signature in ssa{ss}s
signature out
parameters
to_jid
the JID to who we send the presence data (emtpy string for broadcast)
DEFAULT: ''
show
as for presenceUpdate
DEFAULT: ''
statuses
as for presenceUpdate
DEFAULT: {}
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
DEFAULT: "@DEFAULT@"

subscription

Send subscription request/answer to a contact


category core
signature in sss
signature out
parameters
sub_type
as for subscribe
entity
as for subscribe
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
DEFAULT: "@DEFAULT@"

updateContact

update a contact in profile's roster


This method is asynchronous

category core
signature in ssass
signature out
parameters
entity_jid
JID update in roster
name
roster's name for the entity
groups
list of group where the entity is
profile_key
Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
DEFAULT: "@DEFAULT@"

Generated on 2018-06-04 11:59:38.253957