[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=jid_s: the JID that we were assigned by the server, as the resource might differ from the JID we asked for.
doc_param_1=%(doc_profile)s

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

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

[message_new]
type=signal
category=core
sig_in=sdssa{ss}a{ss}sss
doc=A message has been received
doc_param_0=uid: unique ID of the message (id specific to Libervia, 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

[message_update]
type=signal
category=core
sig_in=ssss
doc=An existing message has been updated
doc_param_0=uid: unique ID of the message (id specific to Libervia, this is *NOT* an XMPP id)
doc_param_1=message_type: Type of the update (can be "EDIT", "REACTION", or any of C.MESS_UPDATE_*)
doc_param_2=message_data: JSON serialized dictionary containing the updated message data. Keys and values will depend on the specific message and use case.
doc_param_3=%(doc_profile)s

[message_encryption_started]
type=signal
category=core
sig_in=sss
doc=A message encryption session has been started
doc_param_0=to_jid: JID of the recipient (bare jid if it's encrypted for all devices)
doc_param_1=encryption_data: (JSON_OBJ) data of the encryption algorithm used, encoded as a json object.
    it always has the following keys:
        - name: human readable name of the algorithm
        - namespace: namespace of the encryption plugin
    following keys are present if suitable:
        - directed_devices: list or resource where session is encrypted
doc_param_2=%(doc_profile_key)s

[message_encryption_stopped]
type=signal
category=core
sig_in=sa{ss}s
doc=A message encryption session has been stopped
doc_param_0=to_jid: JID of the recipient (full jid if it's only stopped for one device)
doc_param_1=encryption_data: data of the encryption algorithm stopped, has a least following keys:
    - name: human readable name of the algorithm
    - namespace: namespace of the encryption plugin
doc_param_2=%(doc_profile_key)s

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

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

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

[action_new]
type=signal
category=core
sig_in=ssis
doc=A frontend action is requested
doc_param_0=action_data: a serialised dict where key can be:
    - xmlui: a XMLUI describing the action
    - 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

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

[notification_new]
type=signal
category=core
sig_in=sdssssbidss
doc=A new notification has been emitted
doc_param_0=id: unique identifier of the notification
doc_param_1=timestamp: notification creation time
doc_param_2=type: type of the notification
doc_param_3=body_plain: plain text body of the notification
doc_param_4=body_rich: rich text (XHTML) body of the notification. Optional.
doc_param_5=title: optional title of the notification
doc_param_6=requires_action: True if the notification requires user action (e.g. a dialog needs to be answered), False otherwise
doc_param_7=priority: how urgent the notification is, represented as an enumeration value
doc_param_8=expire_at: expiration timestamp for the notification. Optional.
doc_param_9=extra: additional serialized data associated with the notification
doc_param_10=profile: profile associated with the notification. C.PROF_KEY_ALL can be used for global notifications.

[notification_deleted]
type=signal
category=core
sig_in=ss
doc=A new notification has been emitted
doc_param_0=id: id of the deleted notification
doc_param_1=profile: profile of the deleted application, or C.PROF_KEY_ALL for a global notification

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

[progress_finished]
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 ([progress_error] 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

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

[_debug]
type=signal
category=core
sig_in=sa{ss}s
doc=Debug method, useful for developers
doc_param_0=action: action to do
doc_param_1=params: action parameters
doc_param_2=%(doc_profile)s

;methods

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

[init_pre_script]
async=
type=method
category=core
sig_in=
sig_out=
doc=Return when backend is nearly initialised, just before init script is run, if any.

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

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

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

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

[profile_set_default]
type=method
category=core
sig_in=s
sig_out=
doc_param_0=%(doc_profile)s
doc=Set default profile

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

[entities_data_get]
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
 values are serialised
 if key doesn't exist for a jid, the resulting dictionary will not have it

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

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

[profile_start_session]
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 Libervia profile password
doc_param_1=%(doc_profile_key)s
doc_return=D(bool):
        - True if the profile session was already started
        - False else

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

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

[contact_get]
async=
type=method
category=core
sig_in=ss
sig_out=(a{ss}as)
param_1_default="@DEFAULT@"
doc=Return informations in roster about a contact
doc_param_1=%(doc_profile_key)s
doc_return=tuple with the following values:
 - list of attributes as in [contact_new]
 - groups where the contact is

[contacts_get]
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 [contact_new]
 - groups where the contact is

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

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

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

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

[message_send]
async=
type=method
category=core
sig_in=sa{ss}a{ss}sss
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: (serialised) optional data that can be used by a plugin to build more specific messages 
doc_param_5=%(doc_profile_key)s

[message_encryption_start]
async=
type=method
category=core
sig_in=ssbs
sig_out=
param_1_default=''
param_2_default=False
param_3_default="@NONE@"
doc=Start an encryption session
doc_param_0=to_jid: JID of the recipient (bare jid if it must be encrypted for all devices)
doc_param_1=namespace: namespace of the encryption algorithm to use
doc_param_2=replace: if True and an encryption session already exists, it will be replaced by this one
    else a ConflictError will be raised
doc_param_3=%(doc_profile_key)s

[message_encryption_stop]
async=
type=method
category=core
sig_in=ss
sig_out=
doc=Stop an encryption session
doc_param_0=to_jid: JID of the recipient (full jid if encryption must be stopped for one device only)
doc_param_1=%(doc_profile_key)s

[message_encryption_get]
type=method
category=core
sig_in=ss
sig_out=s
doc=Retrieve encryption data for a given entity
doc_param_0=to_jid: bare JID of the recipient
doc_param_1=%(doc_profile_key)s
doc_return=(JSON_OBJ) empty string if session is unencrypted, else a json encoded objects.
    In case of dict, following keys are always present:
        - name: human readable name of the encryption algorithm
        - namespace: namespace of the plugin
    following key can be present if suitable:
        - directed_devices: list or resource where session is encrypted

[encryption_namespace_get]
type=method
category=core
sig_in=s
sig_out=s
doc=Get algorithm namespace from its name

[encryption_plugins_get]
type=method
category=core
sig_in=
sig_out=s
doc=Retrieve registered plugins for encryption

[encryption_trust_ui_get]
async=
type=method
category=core
sig_in=sss
sig_out=s
doc=Get XMLUI to manage trust for given encryption algorithm
doc_param_0=to_jid: bare JID of entity to manage
doc_param_1=namespace: namespace of the algorithm to manage
doc_param_2=%(doc_profile_key)s
doc_return=(XMLUI) UI of the trust management

[presence_set]
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 [presence_update]
doc_param_2=statuses: as for [presence_update]
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

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

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

[param_get_a]
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 [param_set]
doc_param_1=category: as for [param_set]
doc_param_2=attribute: Name of the attribute
doc_param_3=%(doc_profile_key)s

[private_data_get]
async=
type=method
category=core
sig_in=sss
sig_out=s
doc=Retrieve private data
doc_param_0=namespace: unique namespace to use
doc_param_1=key: key of the data to set
doc_param_2=%(doc_profile_key)s
doc_return=serialised data

[private_data_set]
async=
type=method
category=core
sig_in=ssss
sig_out=
doc=Store private data
doc_param_0=namespace: unique namespace to use
doc_param_1=key: key of the data to set
doc_param_2=data: serialised data
doc_param_3=%(doc_profile_key)s

[private_data_delete]
async=
type=method
category=core
sig_in=sss
sig_out=
doc=Delete private data
doc_param_0=namespace: unique namespace to use
doc_param_1=key: key of the data to delete
doc_param_3=%(doc_profile_key)s

[param_get_a_async]
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 [param_set]
doc_param_1=category: as for [param_set]
doc_param_2=attribute: Name of the attribute
doc_param_3=%(doc_security_limit)s
doc_param_4=%(doc_profile_key)s

[params_values_from_category_get_async]
async=
type=method
category=code
sig_in=sisss
sig_out=a{ss}
param_1_default=-1
param_2_default=""
param_3_default=""
param_4_default="@DEFAULT@"
doc=Get "attribute" for all params of a category
doc_param_0=category: as for [param_set]
doc_param_1=%(doc_security_limit)s
doc_param_2=app: name of the frontend requesting the parameters, or '' to get all parameters
doc_param_3=extra: extra options/filters
doc_param_4=%(doc_profile_key)s

[param_ui_get]
async=
type=method
category=core
sig_in=isss
sig_out=s
param_0_default=-1
param_1_default=''
param_2_default=''
param_3_default="@DEFAULT@"
doc=Return a Libervia 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=extra: extra options/filters
doc_param_3=%(doc_profile_key)s

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

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

[history_get]
async=
type=method
category=core
sig_in=ssiba{ss}s
sig_out=a(sdssa{ss}a{ss}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 be one of those, values are separated by spaces
    - not_types: type must not be one of those, values are separated by spaces
    - before_uid: check only message received before message with given uid
doc_param_5=%(doc_profile)s
doc_return=Ordered list (by timestamp) of data as in [message_new] (without final profile)

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

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

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

[roster_resync]
async=
type=method
category=core
sig_in=s
sig_out=
param_0_default="@DEFAULT@"
doc=Do a full resynchronisation of roster with server
doc_param_0=%(doc_profile_key)s

[action_launch]
async=
type=method
category=core
sig_in=sss
sig_out=s
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

[actions_get]
type=method
category=core
sig_in=s
sig_out=a(ssi)
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 [action_new] (without the profile)

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

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

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

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

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

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

[disco_infos]
async=
type=method
category=core
sig_in=ssbs
sig_out=(asa(sss)a{sa(a{ss}as)})
param_1_default=u''
param_2_default=True
param_3_default="@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=use_cache: use cached data if available
doc_param_3=%(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

[disco_items]
async=
type=method
category=core
sig_in=ssbs
sig_out=a(sss)
param_1_default=u''
param_2_default=True
param_3_default="@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=use_cache: use cached data if available
doc_param_3=%(doc_profile_key)s
doc_return=array of tuple (entity, node identifier, name)

[disco_find_by_features]
async=
type=method
category=core
sig_in=asa(ss)bbbbbs
sig_out=(a{sa(sss)}a{sa(sss)}a{sa(sss)})
param_2_default=False
param_3_default=True
param_4_default=True
param_5_default=True
param_6_default=False
param_7_default="@DEFAULT@"
doc=Discover items of an entity
doc_param_0=namespaces: namespaces of the features to check
doc_param_1=identities: identities to filter
doc_param_2=bare_jid: if True only retrieve bare jids
    if False, retrieve full jids of connected resources
doc_param_3=service: True to check server's services
doc_param_4=roster: True to check connected devices from people in roster
doc_param_5=own_jid: True to check profile's jid
doc_param_6=local_device: True to check device on which the backend is running
doc_param_7=%(doc_profile_key)s
doc_return=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

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

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

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

[devices_infos_get]
async=
type=method
category=core
sig_in=ss
sig_out=s
doc=Get various informations on an entity devices
doc_param_0=bare_jid: get data on known devices from this entity
    empty string to get devices of the profile
doc_param_1=%(doc_profile_key)s
doc_return=list of known devices, where each item is a dict with a least following keys:
    resource: device resource

[namespaces_get]
type=method
category=core
sig_in=
sig_out=a{ss}
doc=Get a dict to short name => whole namespaces
doc_return=namespaces mapping

[image_check]
type=method
category=core
sig_in=s
sig_out=s
doc=Analyze an image a return a report
doc_return=serialized report

[image_resize]
async=
type=method
category=core
sig_in=sii
sig_out=s
doc=Create a new image with desired size
doc_param_0=image_path: path of the image to resize
doc_param_1=width: width of the new image
doc_param_2=height: height of the new image
doc_return=path of the new image with desired size
    the image must be deleted once not needed anymore

[image_generate_preview]
async=
type=method
category=core
sig_in=ss
sig_out=s
doc=Generate a preview of an image in cache
doc_param_0=image_path: path of the original image
doc_param_1=%(doc_profile_key)s
doc_return=path to the preview in cache

[image_convert]
async=
type=method
category=core
sig_in=ssss
sig_out=s
doc=Convert an image to an other format
doc_param_0=source: path of the image to convert
doc_param_1=dest: path to the location where the new image must be stored.
    Empty string to generate a file in cache, unique to the source
doc_param_3=extra: serialised extra
doc_param_4=profile_key: either profile_key or empty string to use common cache
    this parameter is used only when dest is empty
doc_return=path to the new converted image

[notification_add]
type=method
category=core
sig_in=ssssbbsdss
sig_out=
doc=Add a new notification
doc_param_0=type_: Notification type
doc_param_1=body_plain: Plain text body of the notification
doc_param_2=body_rich: Rich text body of the notification (optional, can be empty string for default)
doc_param_3=title: Title of the notification (optional, can be empty string for default)
doc_param_4=is_global: True if the notification is for all profiles
doc_param_5=requires_action: Indicates if the notification requires action
doc_param_7=priority: Priority level of the notification (e.g. MEDIUM, HIGH, etc.)
doc_param_8=expire_at: Expiration timestamp for the notification (optional, can be 0 for none)
doc_param_9=extra: Additional details for the notification as a dictionary (optional, can be empty dictionary)
doc_param_10=%(doc_profile_key)s: Profile key (use "@ALL@" for all profiles)

[notifications_get]
type=method
category=core
sig_in=ss
sig_out=s
doc=Retrieve notifications based on provided filters
doc_param_0=filters: a dictionary with filter criteria for notifications retrieval
doc_param_1=%(doc_profile_key)s or @ALL@ for all profiles
doc_return=list of Notification objects. The exact structure will depend on your Notification class.

[notification_delete]
type=method
category=core
sig_in=sbs
sig_out=
doc=Delete a notification
doc_param_0=id_: ID of the notification to delete
doc_param_1=is_global: true if the notification is a global one
doc_param_2=profile_key: Profile key (use "@ALL@" for all profiles)

[notifications_expired_clean]
type=method
category=core
sig_in=ds
sig_out=
doc=Cleans expired notifications and older profile-specific notifications
doc_param_0=limit_timestamp: Timestamp limit for older notifications. If -1.0, only truly expired notifications are removed.
doc_param_1=profile_key: Profile key (use "@NONE@" to indicate no specific profile, otherwise only notification for given profile will be expired, in addition to truly expired notifications).