[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
  - info_type: subtype for info messages
doc_param_8=%(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

[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

[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=

[profileNameGet]
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

[profilesListGet]
type=method
category=core
sig_in=bb
sig_out=as
param_0_default=True
param_1_default=False
doc_param_0=clients: get clients profiles
doc_param_1=components: get components profiles
doc=Get list of profiles

[profileSetDefault]
type=method
category=core
sig_in=s
sig_out=
doc_param_0=%(doc_profile)s
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

[profileCreate]
async=
type=method
category=core
sig_in=sss
sig_out=
param_1_default=''
param_2_default=''
doc=Create a new profile
doc_param_0=%(doc_profile)s
doc_param_1=password: password of the profile
doc_param_2=component: set to component entry point if it is a component, else use empty string
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
 - NotFound: component entry point is not available

[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

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

[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 subject, 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=ssiba{ss}s
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=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
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)

[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]

[menusGet]
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

[menuLaunch]
async=
type=method
category=core
sig_in=sasa{ss}is
sig_out=a{ss}
doc=Launch a registred menu
doc_param_0=menu_type: type of the menu (C.MENU_*)
doc_param_1=path: canonical (untranslated) path of the menu
doc_param_2=data: optional data
doc_param_3=%(doc_security_limit)s
doc_param_4=%(doc_profile_key)s
doc_return=dict where key can be:
    - xmlui: a XMLUI need to be displayed

[menuHelpGet]
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=sss
sig_out=(asa(sss)a{sa(a{ss}as)})
param_1_default=u''
param_2_default=u"@DEFAULT@"
doc=Discover infos on an entity
doc_param_0=entity_jid: JID to discover
doc_param_1=node: node to use
doc_param_2=%(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=sss
sig_out=a(sss)
param_1_default=u''
param_2_default=u"@DEFAULT@"
doc=Discover items of an entity
doc_param_0=entity_jid: JID to discover
doc_param_1=node: node to use
doc_param_2=%(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)

[sessionInfosGet]
async=
type=method
category=core
sig_in=s
sig_out=a{ss}
doc=Get various informations on current profile session
doc_param_0=%(doc_profile_key)s
doc_return=session informations, with at least the following keys:
    jid: current full jid
    started: date of creation of the session (Epoch time)