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

;signals

[connected]
type=signal
category=core
sig_in=s
doc=Connection is done
doc_param_0=%(doc_profile)s

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

[connectionError]
type=signal
category=core
sig_in=ss
doc=Something went wront with the connection
doc_param_0=error_type: Why the connection got wrong, can be
 - AUTH_ERROR: Authentification error
doc_param_1=%(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

[newMessage]
type=signal
category=core
sig_in=ssssa{ss}s
doc=A message has been received
doc_param_0=from_jid: JID where the message is comming from
doc_param_1=message: Message itself
doc_param_2=mess_type: Type of the message (cf RFC 3921 #2.1.1)
doc_param_3=to_jid: JID where the message must be sent
doc_param_4=extra: extra message information
doc_param_5=%(doc_profile)s

[newAlert]
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 informations.
doc_param_0=entity_jid: JID from which we have presence informations
doc_param_1=show: availability status (see RFC 3921 #2.2.2.1)
doc_param_2=priority: Priority level of the ressource (see RFC 3921 #2.2.2.3)
doc_param_3=statuses: Natural language description of the availability status (see RFC 3921 #2.2.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 3921 #9)
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]
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

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

;methods

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

[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, or empty string if the profile doesn't exist

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

[getEntityData]
type=method
category=core
sig_in=sass
sig_out=a{ss}
doc=Get data 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 neither have the key

[createProfile]
deprecated=
type=method
category=core
sig_in=s
sig_out=i
doc=Create a new profile
doc_param_0=%(doc_profile)s
doc_return=status of the creation:
 - 0: Profile created
 - 1: The profile name already exists

[asyncCreateProfile]
async=
type=method
category=core
sig_in=s
sig_out=
doc=Create a new profile
doc_param_0=%(doc_profile)s
doc_return=callback is called when profile actually exists in database and memory
errback is called with error constant as parameter:
 - "CONFLICT": The profile name already exists
 - "CANCELED": profile creation canceled

[deleteProfile]
type=method
category=core
sig_in=s
sig_out=i
doc=Delete a profile
doc_param_0=%(doc_profile)s
doc_return=status of the deletion:
 - 0: Profile deleted
 - 1: The profile doesn't exists

[registerNewAccount]
deprecated=
type=method
category=core
sig_in=ssssi
sig_out=s
param_4_default=5222
doc=Register a new account on a given server
doc_param_0=login: login of the account
doc_param_1=password: password of the account
doc_param_2=email: email of the account
doc_param_3=host: host of the server to register to
doc_param_4=port: port of the server to register to

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

[asyncConnect]
async=
type=method
category=core
sig_in=s
sig_out=
param_0_default="@DEFAULT@"
doc=Connect a profile
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]
type=method
category=core
sig_in=s
sig_out=a(sa{ss}as)
param_0_default="@DEFAULT@"
doc=Return informations about all contacts
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 informations 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

[getLastResource]
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 last resource connected of the contact, or ""

[getPresenceStatus]
type=method
category=core
sig_in=s
sig_out=a{sa{s(sia{ss})}}
param_0_default="@DEFAULT@"
doc=Return presence informations 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]


[sendMessage]
type=method
category=core
sig_in=ssssa{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
doc_param_2=subject: Subject of the message ('' if no subject)
doc_param_3=mess_type: Type of the message (cf RFC 3921 #2.1.1) or "auto" for automatic type detection
doc_param_4=options: 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=ssia{ss}s
sig_out=
param_0_default=''
param_1_default=''
param_2_default=0
param_3_default={}
param_4_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=priority: as for [presenceUpdate]
doc_param_3=statuses: as for [presenceUpdate]
doc_param_4=%(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=security_limit: -1 means no security then the higher the most secure
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=security_limit: -1 means no security then the higher the most secure
doc_param_4=%(doc_profile_key)s

[getParamsUI]
async=
type=method
category=core
sig_in=is
sig_out=s
param_0_default=-1
param_1_default="@DEFAULT@"
doc=Return a SàT XMLUI for parameters
doc_param_0=security_limit: -1 means no security then the higher the most secure
doc_param_1=%(doc_profile_key)s

[getParams]
async=
type=method
category=core
sig_in=is
sig_out=s
param_0_default=-1
param_1_default="@DEFAULT@"
doc=Return XML of parameters
doc_param_0=security_limit: -1 means no security then the higher the most secure
doc_param_1=%(doc_profile_key)s

[getParamsForCategory]
async=
type=method
category=core
sig_in=sis
sig_out=s
param_1_default=-1
param_2_default="@DEFAULT@"
doc=Return a xml of all params in a category
doc_param_0=category: Category to get
doc_param_1=security_limit: -1 means no security then the higher the most secure
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

[getHistory]
async=
type=method
category=core
sig_in=ssibs
sig_out=a(dssss)
param_3_default=True
param_4_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=%(doc_profile)s
doc_return=Ordered list (by timestamp) of tuples (timestamp, full from_jid, full to_jid, message, type)

[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]
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]
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]
type=method
category=core
sig_in=sa{ss}s
sig_out=s
param_2_default="@DEFAULT@"
doc=Launch a specific action
doc_param_0=action_type: type of the action which can be:
 - button: A button is pushed
doc_param_1=data: action_type dependant data
doc_param_2=%(doc_profile_key)s

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

[getProgress]
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 information:
 - position: current position
 - size: end position

[getMenus]
type=method
category=core
sig_in=
sig_out=a(sss)
doc=Get all additional menus
doc_return=list of tuple with the following value:
 - category: Category of the menu
 - name: Name of the menu
 - menu_type: Type which can be:
    * NORMAL: Classical application menu

[getMenuHelp]
type=method
category=core
sig_in=sss
sig_out=s
param_2="NORMAL"
doc=Get help information for a menu
doc_param_0=category: Category of the menu
doc_param_1=name: Name of the menu
doc_param_2=menu_type: Type of the menu as in [getMenus] return value
doc_return=Help string

[callMenu]
type=method
category=core
sig_in=ssss
sig_out=s
doc=Execute action associated with a menu
doc_param_0=category: as in [getMenuHelp]
doc_param_1=name: as in [getMenuHelp]
doc_param_2=menu_type: as in [getMenuHelp]
doc_param_3=%(doc_profile_key)s
doc_return=return an actionId or the empty string if something went wrong