view src/bridge/bridge_constructor/bridge_template.ini @ 1955:633b5c21aefd

backend, frontend: messages refactoring (huge commit, not finished): /!\ database schema has been modified, do a backup before updating message have been refactored, here are the main changes: - languages are now handled - all messages have an uid (internal to SàT) - message updating is anticipated - subject is now first class - new naming scheme is used newMessage => messageNew, getHistory => historyGet, sendMessage => messageSend - minimal compatibility refactoring in quick_frontend/Primitivus, better refactoring should follow - threads handling - delayed messages are saved into history - info messages may also be saved in history (e.g. to keep track of people joining/leaving a room) - duplicate messages should be avoided - historyGet return messages in right order, no need to sort again - plugins have been updated to follow new features, some of them need to be reworked (e.g. OTR) - XEP-0203 (Delayed Delivery) is now fully handled in core, the plugin just handle disco and creation of a delay element - /!\ jp and Libervia are currently broken, as some features of Primitivus It has been put in one huge commit to avoid breaking messaging between changes. This is the main part of message refactoring, other commits will follow to take profit of the new features/behaviour.
author Goffi <goffi@goffi.org>
date Tue, 24 May 2016 22:11:04 +0200
parents 74676624ad5d
children a2bc5089c2eb
line wrap: on
line source

[DEFAULT]
doc_profile=profile: Name of the profile.
doc_profile_key=profile_key: Profile key which can be either a magic (eg: @DEFAULT@) or the name of an existing profile.
doc_security_limit=security_limit: -1 means no security, 0 is the maximum security then the higher the less secure

;signals

[connected]
type=signal
category=core
sig_in=ss
doc=Connection is done
doc_param_0=%(doc_profile)s
doc_param_1=jid_s: the JID that we were assigned by the server, as the resource might differ from the JID we asked for.

[disconnected]
type=signal
category=core
sig_in=s
doc=Connection is finished or lost
doc_param_0=%(doc_profile)s

[newContact]
type=signal
category=core
sig_in=sa{ss}ass
doc=New contact received in roster
doc_param_0=contact_jid: JID which has just been added
doc_param_1=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
doc_param_2=groups: Roster's groups where the contact is
doc_param_3=%(doc_profile)s

[messageNew]
type=signal
category=core
sig_in=sdssa{ss}a{ss}sa{ss}s
doc=A message has been received
doc_param_0=uid: unique ID of the message (id specific to SàT, this it *NOT* an XMPP id)
doc_param_1=timestamp: when the message was sent (or declared sent for delayed messages)
doc_param_2=from_jid: JID where the message is comming from
doc_param_3=to_jid: JID where the message must be sent
doc_param_4=message: message itself, can be in several languages (key is language code or '' for default)
doc_param_5=subject: subject of the message, can be in several languages (key is language code or '' for default)
doc_param_6=mess_type: Type of the message (cf RFC 6121 §5.2.2) + C.MESS_TYPE_INFO (system info)
doc_param_7=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
doc_param_8=%(doc_profile)s

[newAlert]
deprecated=
type=signal
category=core
sig_in=ssss
doc=A new alert happened
doc_param_0=message: Body of the alert
doc_param_1=title: Title of the alert
doc_param_2=alert_type: Type of the alert, can be:
 - INFO: Informative message
 - ERROR: something went wrong
doc_param_3=%(doc_profile)s

[presenceUpdate]
type=signal
category=core
sig_in=ssia{ss}s
doc=Somebody changed his presence information.
doc_param_0=entity_jid: JID from which we have presence informatios
doc_param_1=show: availability status (see RFC 6121 §4.7.2.1)
doc_param_2=priority: Priority level of the ressource (see RFC 6121 §4.7.2.3)
doc_param_3=statuses: Natural language description of the availability status (see RFC 6121 §4.7.2.2)
doc_param_4=%(doc_profile)s

[subscribe]
type=signal
category=core
sig_in=sss
doc=Somebody wants to be added in roster
doc_param_0=sub_type: Subscription states (see RFC 6121 §3)
doc_param_1=entity_jid: JID from which the subscription is coming
doc_param_2=%(doc_profile)s

[paramUpdate]
type=signal
category=core
sig_in=ssss
doc=A parameter has been changed
doc_param_0=name: Name of the updated parameter
doc_param_1=value: New value of the parameter
doc_param_2=category: Category of the updated parameter
doc_param_3=%(doc_profile)s

[contactDeleted]
type=signal
category=core
sig_in=ss
doc=A contact has been supressed from roster
doc_param_0=entity_jid: JID of the contact removed from roster
doc_param_1=%(doc_profile)s

[askConfirmation]
deprecated=
type=signal
category=core
sig_in=ssa{ss}s
doc=A confirmation is needed for an action
doc_param_0=id: Id of the confirmation query
doc_param_1=conf_type: Type of the confirmation, can be:
 - YES/NO: A question which need a yes or no answer
 - FILE_TRANSFER: A confirmation is needed before transfering a file
doc_param_2=data: conf_type dependent data
doc_param_3=%(doc_profile)s

[actionNew]
type=signal
category=core
sig_in=a{ss}sis
doc=A frontend action is requested
doc_param_0=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
doc_param_1=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.
doc_param_2=%(doc_security_limit)s
doc_param_3=%(doc_profile)s

[actionResult]
deprecated=
type=signal
category=core
sig_in=ssa{ss}s
doc=Requested result of an action
doc_param_0=answer_type: Type of the answer, can be:
 - SUPPRESS: The action is managed, the id MUST be removed from queue
 - XMLUI: A SàT XMLUI interface is sent
 - ERROR: Something went wrong when doing the action
 - RESULT: General result, interpretation depend of the action
doc_param_1=id: Id of the action
doc_param_2=data: answer_type specific data
doc_param_3=%(doc_profile)s

[actionResultExt]
deprecated=
type=signal
category=core
sig_in=ssa{sa{ss}}s
doc=Requested result of an action (Extended)
doc_param_0=answer_type: Same as for [actionResult] but with the following additional one:
 - DICT_DICT: As RESULT, but returned as a dictionary of dictionary
doc_param_1=id: Id of the action
doc_param_2=data: answer_type specific data
doc_param_3=%(doc_profile)s

[entityDataUpdated]
type=signal
category=core
sig_in=ssss
doc=An entity's data has been updated
doc_param_0=jid: entity's bare jid
doc_param_1=name: Name of the updated value
doc_param_2=value: New value
doc_param_3=%(doc_profile)s

[progressStarted]
type=signal
category=core
sig_in=sa{ss}s
doc=A progressing operation has just started
doc_param_0=id: id of the progression operation
doc_param_1=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
doc_param_2=%(doc_profile)s

[progressFinished]
type=signal
category=core
sig_in=sa{ss}s
doc=A progressing operation is finished
doc_param_0=id: id of the progression operation
doc_param_1=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)
doc_param_2=%(doc_profile)s

[progressError]
type=signal
category=core
sig_in=sss
doc=There was an error during progressing operation
doc_param_0=id: id of the progression operation
doc_param_1=error: error message
doc_param_2=%(doc_profile)s

;methods

[getReady]
async=
type=method
category=core
sig_in=
sig_out=
doc=Return when backend is initialised

[getVersion]
type=method
category=core
sig_in=
sig_out=s
doc=Get "Salut à Toi" full version

[getFeatures]
type=method
category=core
sig_in=s
sig_out=a{sa{ss}}
doc=Get available features and plugins
 features can changes for differents profiles, e.g. because of differents server capabilities
doc_param_0=%(doc_profile_key)s
doc_return=dictionary of available features:
 plugin import name is used as key, data is an other dict managed by the plugin
async=

[getProfileName]
type=method
category=core
sig_in=s
sig_out=s
param_0_default="@DEFAULT@"
doc=Get real profile name from profile key
doc_param_0=%(doc_profile_key)s
doc_return=Real profile name

[getProfilesList]
type=method
category=core
sig_in=
sig_out=as
doc=Get all profiles

[profileSetDefault]
type=method
category=core
sig_in=s
sig_out=
doc=Set default profile

[getEntityData]
type=method
category=core
sig_in=sass
sig_out=a{ss}
doc=Get data in cache for an entity
doc_param_0=jid: entity's bare jid
doc_param_1=keys: list of keys to get
doc_param_2=%(doc_profile)s
doc_return=dictionary of asked key,
 if key doesn't exist, the resulting dictionary will not have the key

[getEntitiesData]
type=method
category=core
sig_in=asass
sig_out=a{sa{ss}}
doc=Get data in cache for several entities at once
doc_param_0=jids: list of entities bare jid, or empty list to have all jids in cache
doc_param_1=keys: list of keys to get
doc_param_2=%(doc_profile)s
doc_return=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

[asyncCreateProfile]
async=
type=method
category=core
sig_in=ss
sig_out=
param_1_default=''
doc=Create a new profile
doc_param_0=%(doc_profile)s
doc_param_1=password: password of the profile
doc_return=callback is called when profile actually exists in database and memory
errback is called with error constant as parameter:
 - ConflictError: the profile name already exists
 - CancelError: profile creation canceled

[asyncDeleteProfile]
async=
type=method
category=core
sig_in=s
sig_out=
doc=Delete a profile
doc_param_0=%(doc_profile)s
doc_return=callback is called when profile has been deleted from database and memory
errback is called with error constant as parameter:
 - ProfileUnknownError: the profile name is unknown
 - ConnectedProfileError: a connected profile would not be deleted

[asyncConnect]
async=
type=method
category=core
sig_in=ss
sig_out=b
param_0_default="@DEFAULT@"
param_1_default=''
doc=Connect a profile
doc_param_0=%(doc_profile_key)s
doc_param_1=password: the SàT profile password
doc_return=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

[profileStartSession]
async=
type=method
category=core
sig_in=ss
sig_out=b
param_0_default=''
param_1_default="@DEFAULT@"
doc=Start a profile session without connecting it (if it's not already the case)
doc_param_0=password: the SàT profile password
doc_param_1=%(doc_profile_key)s
doc_return=D(bool):
        - True if the profile session was already started
        - False else

[profileIsSessionStarted]
type=method
category=core
sig_in=s
sig_out=b
param_0_default="@DEFAULT@"
doc=Tell if a profile session is loaded
doc_param_0=%(doc_profile_key)s

[disconnect]
type=method
category=core
sig_in=s
sig_out=
param_0_default="@DEFAULT@"
doc=Disconnect a profile
doc_param_0=%(doc_profile_key)s

[isConnected]
type=method
category=core
sig_in=s
sig_out=b
param_0_default="@DEFAULT@"
doc=Tell if a profile is connected
doc_param_0=%(doc_profile_key)s

[getContacts]
async=
type=method
category=core
sig_in=s
sig_out=a(sa{ss}as)
param_0_default="@DEFAULT@"
doc=Return information about all contacts (the roster)
doc_param_0=%(doc_profile_key)s
doc_return=array of tuples with the following values:
 - JID of the contact
 - list of attributes as in [newContact]
 - groups where the contact is

[getContactsFromGroup]
type=method
category=core
sig_in=ss
sig_out=as
param_1_default="@DEFAULT@"
doc=Return information about all contacts
doc_param_0=group: name of the group to check
doc_param_1=%(doc_profile_key)s
doc_return=array of jids

[getMainResource]
type=method
category=core
sig_in=ss
sig_out=s
param_1_default="@DEFAULT@"
doc=Return the last resource connected for a contact
doc_param_0=contact_jid: jid of the contact
doc_param_1=%(doc_profile_key)s
doc_return=the resource connected of the contact with highest priority, or ""

[getPresenceStatuses]
type=method
category=core
sig_in=s
sig_out=a{sa{s(sia{ss})}}
param_0_default="@DEFAULT@"
doc=Return presence information of all contacts
doc_param_0=%(doc_profile_key)s
doc_return=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]

[getWaitingSub]
type=method
category=core
sig_in=s
sig_out=a{ss}
param_0_default="@DEFAULT@"
doc=Get subscription requests in queue
doc_param_0=%(doc_profile_key)s
doc_return=Dict where contact JID is the key, and value is the subscription type

[getWaitingConf]
type=method
category=core
sig_in=s
sig_out=a(ssa{ss})
doc=Get confirmations requests in queue
doc_param_0=%(doc_profile_key)s
doc_return=List of confirmation request data, same as for [askConfirmation]


[messageSend]
async=
type=method
category=core
sig_in=sa{ss}a{ss}sa{ss}s
sig_out=
param_2_default=''
param_3_default="auto"
param_4_default={}
param_5_default="@NONE@"
doc=Send a message
doc_param_0=to_jid: JID of the recipient
doc_param_1=message: body of the message:
    key is the language of the body, use '' when unknown
doc_param_2=subject: Subject of the message
    key is the language of the subkect, use '' when unknown
doc_param_3=mess_type: Type of the message (cf RFC 6121 §5.2.2) or "auto" for automatic type detection
doc_param_4=extra: optional data that can be used by a plugin to build more specific messages 
doc_param_5=%(doc_profile_key)s

[setPresence]
type=method
category=core
sig_in=ssa{ss}s
sig_out=
param_0_default=''
param_1_default=''
param_2_default={}
param_3_default="@DEFAULT@"
doc=Set presence information for the profile
doc_param_0=to_jid: the JID to who we send the presence data (emtpy string for broadcast)
doc_param_1=show: as for [presenceUpdate]
doc_param_2=statuses: as for [presenceUpdate]
doc_param_3=%(doc_profile_key)s

[subscription]
type=method
category=core
sig_in=sss
sig_out=
param_2_default="@DEFAULT@"
doc=Send subscription request/answer to a contact
doc_param_0=sub_type: as for [subscribe]
doc_param_1=entity: as for [subscribe]
doc_param_2=%(doc_profile_key)s

[getConfig]
type=method
category=core
sig_in=ss
sig_out=s
doc=get main configuration option
doc_param_0=section: section of the configuration file (empty string for DEFAULT)
doc_param_1=name: name of the option

[setParam]
type=method
category=core
sig_in=sssis
sig_out=
param_3_default=-1
param_4_default="@DEFAULT@"
doc=Change a parameter
doc_param_0=name: Name of the parameter to change
doc_param_1=value: New Value of the parameter
doc_param_2=category: Category of the parameter to change
doc_param_3=%(doc_security_limit)s
doc_param_4=%(doc_profile_key)s

[getParamA]
type=method
category=core
sig_in=ssss
sig_out=s
param_2_default="value"
param_3_default="@DEFAULT@"
doc=Helper method to get a parameter's attribute *when profile is connected*
doc_param_0=name: as for [setParam]
doc_param_1=category: as for [setParam]
doc_param_2=attribute: Name of the attribute
doc_param_3=%(doc_profile_key)s

[asyncGetParamA]
async=
type=method
category=core
sig_in=sssis
sig_out=s
param_2_default="value"
param_3_default=-1
param_4_default="@DEFAULT@"
doc=Helper method to get a parameter's attribute
doc_param_0=name: as for [setParam]
doc_param_1=category: as for [setParam]
doc_param_2=attribute: Name of the attribute
doc_param_3=%(doc_security_limit)s
doc_param_4=%(doc_profile_key)s

[asyncGetParamsValuesFromCategory]
async=
type=method
category=code
sig_in=sis
sig_out=a{ss}
param_1_default=-1
param_2_default="@DEFAULT@"
doc=Get "attribute" for all params of a category
doc_param_0=category: as for [setParam]
doc_param_1=%(doc_security_limit)s
doc_param_2=%(doc_profile_key)s

[getParamsUI]
async=
type=method
category=core
sig_in=iss
sig_out=s
param_0_default=-1
param_1_default=''
param_2_default="@DEFAULT@"
doc=Return a SàT XMLUI for parameters, eventually restrict the result to the parameters concerning a given frontend
doc_param_0=%(doc_security_limit)s
doc_param_1=app: name of the frontend requesting the parameters, or '' to get all parameters
doc_param_2=%(doc_profile_key)s

[getParamsCategories]
type=method
category=core
sig_in=
sig_out=as
doc=Get all categories currently existing in parameters
doc_return=list of categories

[paramsRegisterApp]
type=method
category=core
sig_in=sis
sig_out=
param_1_default=-1
param_2_default=''
doc=Register frontend's specific parameters
doc_param_0=xml: XML definition of the parameters to be added
doc_param_1=%(doc_security_limit)s
doc_param_2=app: name of the frontend registering the parameters

[historyGet]
async=
type=method
category=core
sig_in=ssibss
sig_out=a(sdssa{ss}a{ss}sa{ss})
param_3_default=True
param_4_default=''
param_5_default="@NONE@"
doc=Get history of a communication between two entities
doc_param_0=from_jid: source JID (bare jid for catch all, full jid else)
doc_param_1=to_jid: dest JID (bare jid for catch all, full jid else)
doc_param_2=limit: max number of history elements to get (0 for the whole history)
doc_param_3=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
doc_param_4=search: pattern to filter the history results
doc_param_5=%(doc_profile)s
doc_return=Ordered list (by timestamp) of data as in [messageNew] (without final profile)

[addContact]
type=method
category=core
sig_in=ss
sig_out=
param_1_default="@DEFAULT@"
doc=Add a contact to profile's roster
doc_param_0=entity_jid: JID to add to roster
doc_param_1=%(doc_profile_key)s

[updateContact]
async=
type=method
category=core
sig_in=ssass
sig_out=
param_3_default="@DEFAULT@"
doc=update a contact in profile's roster
doc_param_0=entity_jid: JID update in roster
doc_param_1=name: roster's name for the entity
doc_param_2=groups: list of group where the entity is
doc_param_3=%(doc_profile_key)s

[delContact]
async=
type=method
category=core
sig_in=ss
sig_out=
param_1_default="@DEFAULT@"
doc=Remove a contact from profile's roster
doc_param_0=entity_jid: JID to remove from roster
doc_param_1=%(doc_profile_key)s

[launchAction]
async=
type=method
category=core
sig_in=sa{ss}s
sig_out=a{ss}
param_2_default="@DEFAULT@"
doc=Launch a registred action
doc_param_0=callback_id: id of the registred callback
doc_param_1=data: optional data
doc_param_2=%(doc_profile_key)s
doc_return=dict where key can be:
    - xmlui: a XMLUI need to be displayed

[actionsGet]
type=method
category=core
sig_in=s
sig_out=a(a{ss}si)
param_0_default="@DEFAULT@"
doc=Get all not yet answered actions
doc_param_0=%(doc_profile_key)s
doc_return=list of data as for [actionNew] (without the profile)

[confirmationAnswer]
deprecated=
type=method
category=core
sig_in=sba{ss}s
sig_out=
doc=Give answer to a confirmation request
doc_param_0=id: id of the confirmation request
doc_param_1=accepted: True if the action is confirmed
doc_param_2=data: action specific data
doc_param_3=%(doc_profile)s

[progressGet]
type=method
category=core
sig_in=ss
sig_out=a{ss}
doc=Get progress information for an action
doc_param_0=id: id of the progression status
doc_param_1=%(doc_profile)s
doc_return=dict with progress informations:
 - position: current position
 - size: end position (optional if not known)
 other metadata may be present

[progressGetAllMetadata]
type=method
category=core
sig_in=s
sig_out=a{sa{sa{ss}}}
doc=Get all active progress informations
doc_param_0=%(doc_profile)s or C.PROF_KEY_ALL for all profiles
doc_return= 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]

[progressGetAll]
type=method
category=core
sig_in=s
sig_out=a{sa{sa{ss}}}
doc=Get all active progress informations
doc_param_0=%(doc_profile)s or C.PROF_KEY_ALL for all profiles
doc_return= 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]

[getMenus]
type=method
category=core
sig_in=si
sig_out=a(ssasasa{ss})
doc=Get all additional menus
doc_param_0=language: language in which the menu should be translated (empty string for default)
doc_param_1=security_limit: %(doc_security_limit)s
doc_return=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

[getMenuHelp]
type=method
category=core
sig_in=ss
sig_out=s
param_2="NORMAL"
doc=Get help information for a menu
doc_param_0=menu_id: id of the menu (same as callback_id)
doc_param_1=language: language in which the menu should be translated (empty string for default)
doc_return=Translated help string

[discoInfos]
async=
type=method
category=core
sig_in=ss
sig_out=(asa(sss)a{sa(a{ss}as)})
doc=Discover infos on an entity
doc_param_0=entity_jid: JID to discover
doc_param_1=%(doc_profile_key)s
doc_return=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]
async=
type=method
category=core
sig_in=ss
sig_out=a(sss)
doc=Discover items of an entity
doc_param_0=entity_jid: JID to discover
doc_param_1=%(doc_profile_key)s
doc_return=array of tuple (entity, node identifier, name)

[saveParamsTemplate]
type=method
category=core
sig_in=s
sig_out=b
doc=Save parameters template to xml file
doc_param_0=filename: output filename
doc_return=boolean (True in case of success)

[loadParamsTemplate]
type=method
category=core
sig_in=s
sig_out=b
doc=Load parameters template from xml file
doc_param_0=filename: input filename
doc_return=boolean (True in case of success)