SIP SIMPLE Client SDK

= Configuration API =

[[TOC(WikiStart, Sip*, depth=2)]]

The configuration API is used by the [wiki:SipMiddlewareApi Middleware API] to store and read its settings. By managing the settings of the middleware through this configuration API one can create different applications that behave consistently and inherit the same settings. For example a command line client or a GUI program can read and write their settings through this API. 

The settings can be managed by API calls or by using the provided [wiki:sip_settings sip-settings] command line tool. The configuration API has appropriate defaults so that the middleware can function with a minimum amount of settings. To use the middleware, one must define at least one SIP account:

{{{

sip-settings --account add user@domain password

}}}

== Middleware Settings Index ==

These are the current settings, kept in the modules '''sipsimple.configuration.settings''' and '''sipsimple.account'''. The main classes used to access the settings are Account, BonjourAccount and SIPSimpleSettings. All settings can be accessed as simple attributes. The types of attributes is described for each setting below. When setting the value of an attribute, if it's not of the required type, it will be given to the specified type as the only argument. The modified settings are not saved to the persistent storage until the '''save''' method is called on the main object. Once this is done, a CFGSettingsObjectDidChange notification is sent, the data of which is explained in [wiki:SipConfigurationAPI#SettingsObjectNotifications SettingsObject Notifications].

Only a nillable setting can be assigned the value {{{None}}}, even if the type of the setting would otherwise accept {{{None}}} as an argument. The settings as described below are ''not'' nillable, unless specified explicitely. To reset the value of a setting, the special object {{{sipsimple.configuration.DefaultValue}}} can be assigned to it. If a default value is not explicitely specified below, it defaults to {{{None}}}. Note that a non-nillable setting cannot have the default value of {{{None}}}.

== General ==

{{{

SIP SIMPLE settings:

             +-- default_account = user@example.com

SIP SIMPLE --|-- user_agent = sipsimple

             |-- audio

             |-- chat

             |-- desktop_sharing

             |-- file_transfer

             |-- logs

             |-- msrp

             |-- rtp

             |-- sip

             +-- tls

        +-- alert_device = system_default

audio --|-- input_device = system_default

        |-- output_device = system_default

        |-- sample_rate = 44100

        |-- silent = False

        +-- tail_length = 200

       +

chat --|

       +

                  +

desktop_sharing --|

                  +

                +

file_transfer --|

                +

       +-- pjsip_level = 5

logs --|

       +

       +-- transport = tls

msrp --|

       +

      +-- audio_codec_list = AudioCodecList(['speex', 'G722', 'PCMU', 'PCMA', 'iLBC', 'GSM'])

rtp --|-- port_range = PortRange(start=50000, end=50400)

      +-- timeout = 30

      +-- tcp_port = 0

sip --|-- tls_port = 0

      |-- transport_list = SIPTransportList(['tls', 'tcp', 'udp'])

      +-- udp_port = 0

      +-- ca_list = None

tls --|-- protocol = TLSv1

      +-- timeout = 1000

}}}

The {{{sipsimple.configuration.settings.SIPSimpleSettings}}} class is a singleton can be instantiated and used anywhere after the [wiki:SipConfigurationAPI#ConfigurationManager ConfigurationManager] has been started. 

The settings are explained below:

 '''SIPSimpleSettings.default_account''' (type={{{str}}}, default={{{'bonjour@local'}}}, nillable={{{True}}})::

  A string, which contains the id of the default Account. This setting is managed by the AccountManager and should not be changed manually. See [wiki:SipMiddlewareApi#AccountManager AccountManager] for more information.

 '''SIPSimpleSettings.user_agent''' (type={{{str}}}, default={{{'sipsimple VERSION'}}})::

  This setting will be used to set the value of the User-Agent header in outgoing SIP requests and of the Server header in all SIP responses.

=== Audio ===

 '''SIPSimpleSettings.audio.input_device''' (type={{{str}}}, default={{{None}}}, nillable={{{True}}})::

  The name of the audio device, which will be used for input (recording). If it is set to {{{None}}}, one will be selected automatically by the operating system.

 '''SIPSimpleSettings.audio.output_device''' (type={{{str}}}, default={{{None}}}, nillable={{{True}}})::

  The name of the audio device, which will be used for output (playback). If it is set to {{{default}}, one will be selected automatically by the operating system.

 '''SIPSimpleSettings.audio.alert_device''' (type={{{str}}}, default={{{None}}}, nillable={{{True}}})::

  The name of the alert device, which will be used for alerting the user for incoming session request. If it is set to {{{default}}}, one will be selected automatically by the operating system.

 '''SIPSimpleSettings.audio.tail_length''' (type={{{NonNegativeInteger}}}, default={{{200}}})::

  This setting is used as a parameter for the audio echo cancellation algorithm. It's value is a non-negative integer which represents milliseconds. It specifies the length of the echo cancellation filter.

 '''SIPSimpleSettings.audio.sample_rate''' (type={{{SampleRate}}}, default={{{32}}})::

  This is the sample rate at which the audio system runs. All playback and recording will be done at this rate. If an audio codec has a smaller or larger sample rate, it will be resampled to this value. The possible values are 8, 16 and 32, and represent kHz.

 '''SIPSimpleSettings.audio.silent''' (type={{{bool}}}, default={{{False}}})::

  If this setting is set to True, no audio notifications will be played on the alert device.

=== Chat ===

Empty section for future use.

=== Desktop Sharing ===

Empty section for future use.

=== File Transfer ===

Empty section for future use.

=== Logs ===

 '''SIPSimpleSettings.logs.pjsip_level''' (type={{{NonNegativeInteger}}}, default={{{5}}})::

  This setting controls the amount of log messages generated by the PJSIP core. It must be set to a non-negative integer.

=== MSRP ===

 '''SIPSimpleSettings.msrp.transport''' (type={{{MSRPTransport}}}, default={{{'tls'}}})::

  MSRP can use either TLS or TCP and this setting controls which one should be used.

=== RTP ===

 '''SIPSimpleSettings.rtp.port_range''' (type={{{PortRange}}}, default={{{PortRange(50000, 50400)}}})::

  This setting controls the port range from which ports used by RTP transport will be assigned. The values of the ports need to be in the range 1-65535; the start port must not be larger than the end port.

 '''SIPSimpleSettings.rtp.audio_codec_list''' (type={{{AudioCodecs}}}, default={{{('speex', 'G722', 'PCMU', 'PCMA', 'iLBC', 'GSM')}}})::

  This setting is used to specify the preferred audio codecs, which should be used for audio calls. It must be a tuple containing only strings, which represent the supported codecs (speex, g722, g711, ilbc and gsm), in the order in which they are preferred. This setting can be overridden per account.

=== SIP ===

 '''SIPSimpleSettings.sip.udp_port''' (type={{{Port}}}, default={{{0}}})::

  This is the port on which the Engine will bind and for for sending and receiving UDP packets. It is an integer in the range 0-65535. If it is set to 0, it will be allocated automatically.

 '''SIPSimpleSettings.sip.tcp_port''' (type={{{Port}}}, default={{{0}}})::

  This is the port on which the Engine will listen for TCP connections. It is an integer in the range 0-65535. If it is set to 0, it will be allocated automatically.

 '''SIPSimpleSettings.sip.tls_port''' (type={{{Port}}}, default={{{0}}})::

  This is the port on which the Engine will listen for TLS connections. It is an integer in the range 0-65535. If it is set to 0, it will be allocated automatically.

 '''SIPSimpleSettings.sip.transport_list''' (type={{{Transports}}}, default={{{('tls', 'tcp', 'udp')}}})::

  This setting's value is a tuple, which can only contain the strings 'tls', 'tcp' and 'udp'. It has a double purpose:

   * Only the transports specified here are used to SIP requests associated with normal accounts.

   * The order of the transports specified in this tuple represent the preferred order in which transports should be used. This applies to all SIP requests.

=== TLS ===

 '''SIPSimpleSettings.tls.ca_list''' (type={{{DataPath}}}, default={{{None}}}, nillable={{{True}}})::

  The settings points to a file which contains the CA certificates. In can be {{{None}}}, in which case no CAs are available. If it is set to relative path, it is taken relative to {{{SIPSimpleSettings.user_data_directory}}}; otherwise it is interpreted as an absolute path. In order to access the full path to the history directory, the value attribute on the setting can be used:

  {{{

  SIPSimpleSettings().tls.ca_list.value

  }}}

 '''SIPSimpleSettings.tls.protocol''' (type={{{TLSProtocol}}}, default={{{'TLSv1'}}})::

  This setting sets the version of the TLS protocol which will be used. It is a string and must be one of {{{'TLSv1'}}}, {{{'SSLv2'}}}, {{{'SSL3'}}}, {{{'SSL23'}}}.

 '''SIPSimpleSettings.tls.timeout''' (type={{{NonNegativeInteger}}}, default={{{1000}}})::

  This is the timeout for negotiating TLS connections, in milliseconds. It must be an non-negative integer.

== Account ==

{{{

Account user@example.com:

          +-- display_name = Example User

account --|-- enabled = True

          |-- password = xyz

          |-- dialog_event

          |-- message_summary

          |-- nat_traversal

          |-- presence

          |-- pstn

          |-- rtp

          |-- sip

          |-- tls

          +-- xcap

               +-- enabled = True

dialog_event --|

               +

                  +-- enabled = True

message_summary --|-- voicemail_uri = None

                  +

                +-- msrp_relay = None

nat_traversal --|-- stun_server_list = None

                |-- use_ice = False

                |-- use_msrp_relay_for_inbound = True

                +-- use_msrp_relay_for_outbound = False

           +-- enabled = True

presence --|-- use_rls = True

           +

       +

pstn --|

       +

      +-- audio_codec_list = None

rtp --|-- inband_dtmf = False

      |-- srtp_encryption = optional

      +-- use_srtp_without_tls = False

      +-- outbound_proxy = SIPProxyAddress('sip.example.com', port=5060, transport='udp')

sip --|-- publish_interval = 600

      |-- register = True

      |-- register_interval = 600

      +-- subscribe_interval = 600

      +-- certificate = tls/user@example.com.crt

tls --|-- verify_server = False

      +

       +-- enabled = True

xcap --|-- use_xcap_diff = True

       +-- xcap_root = https://xcap.example.com/xcap-root/

}}}

The Account object is used to represent a normal SIP account registered at a SIP provider. It is uniquely identifiable by it's SIP ID, in the form ''user@domain''. There is exactly one instance of Account per ID, which means that an Account can be accessed by instantianting it anywhere. However, this is not the recommended way of accessing accounts, since it can lead to creating new accounts. The recommended way is by using the [wiki:SipMiddlewareApi#AccountManager AccountManager]. Information about the roles of Account, apart from being a collection of settings, is explained in the [wiki:SipMiddlewareApi#Account Middleware API]. 

The settings that can be accessed on an Account are described below:

 '''Account.id''' (type={{{SIPAddress}}})::

  This is not a setting, as it cannot be modified. It's type is a subclass of {{{str}}}, so it can be used as a normal string, however it also has two attributes {{{username}}} and {{{domain}}} which point to the specific parts of the SIP address.

 '''Account.display_name''' (type={{{str}}}, default={{{None}}}, nillable={{{True}}})::

  The contents of this setting will be sent as part of the ''From'' header when sending SIP requests.

 '''Account.enabled''' (type={{{bool}}}, default={{{False}}})::

  If this setting is set to {{{True}}}, the Account will automatically activate and can be used in other parts of the middleware. More about this is described in [wiki:SipMiddlewareApi#Account Account].

 '''Account.password''' (type={{{str}}}, default={{{''}}})::

  The password, which will be used with this account for authentication.

=== Dialog Event ===

 '''Account.dialog_event.enabled''' (type={{{bool}}}, default={{{True}}})::

  If this setting is set to {{{True}}}, the Account will subscribe to the ''dialog'' event as specified by RFC4235.

=== Message Summary ===

 '''Account.message_summary.enabled''' (type={{{bool}}}, default={{{False}}})::

  If this setting is set to {{{True}}}, the Account will subscribe to the ''message-summary'' event, as specified by RFC3842.

 '''Account.message_summary.voicemail_uri''' (type={{{str}}}, default={{{None}}}, nillable={{{True}}})::

  This is the SIP URI which can be called to listen to the voicemail messages.

=== NAT Traversal ===

 '''Account.nat_traversal.use_ice''' (type={{{bool}}}, default={{{False}}})::

  If this setting is set to {{{True}}}, ICE will be used for finding media candidates for communication over NAT-ed networks.

 '''Account.nat_traversal.stun_server_list''' (type={{{StunServerAddresses}}}, default={{{None}}}, nillable={{{True}}})::

  This setting used for NAT traversal can be used to specify the addresses of the STUN servers used for detecting server reflexive candidates in the context of ICE. The value of the setting is a tuple of objects of type {{{StunServerAddress}}}. If None, the servers will be looked up in the DNS (SRV record _stun._udp.domain).

 '''Account.nat_traversal.msrp_relay''' (type={{{MSRPRelayAddress}}}, default={{{None}}}, nillable={{{True}}})::

  This setting can be used to specify a MSRP relay for use in MSRP connections. If it is set to {{{None}}}. If None, the servers will be looked up in the DNS (SRV record _msrps._tcp.domain).

 '''Account.nat_traversal.use_msrp_relay_for_inbound''' (type={{{bool}}}, default={{{True}}})::

  If this setting is set to {{{True}}}, the MSRP relay will be used for all incoming MSRP connections.

 '''Account.nat_traversal.use_msrp_relay_for_outbound''' (type={{{bool}}}, default={{{False}}})::

  If this setting is set to {{{True}}}, the MSRP relay will be used for all outgoing MSRP connections.

=== Presence  ===

 '''Account.presence.enabled''' (type={{{bool}}}, default={{{True}}})::

  If this setting is set to {{{True}}}, the Account will publish its presence state and subscribe to presence and presence.winfo Event packages. 

 '''Account.presence.use_rls_services''' (type={{{bool}}}, default={{{True}}})::

  If this setting is set to {{{True}}}, the Account will store its Buddy Lists in '''rls-services''' XCAP document  and send a single Subscribe for the ''presence'' event to the RLS services address to obtain the presence information for its buddies. If it is set to {{{False}}}, it will subscribe to each buddy individually.

=== RTP ===

 '''Account.rtp.audio_codecs''' (type={{{AudioCodecs}}}, default={{{None}}}, nillable={{{True}}})::

  This setting is used to specify the preferred audio codecs, which should be used for audio calls of this account. It must be a tuple containing only strings, which represent the supported codecs (speex, g722, g711, ilbc and gsm), in the order in which they are preferred, or {{{None}}} if the codec_list from the general rtp settings is to be used.

 '''Account.audio.srtp_encryption''' (type={{{SRTPEncryption}}}, default={{{'optional'}}})::

  The value of this setting specifies how the account requires the calls to be encrypted using SRTP. It can be one of the values {{{'disabled'}}}, {{{'optional'}}} or {{{'mandatory'}}}.

 '''Account.audio.use_srtp_without_tls''' (type={{{bool}}}, default={{{False}}})::

  If this setting is set to {{{True}}}, SRTP could be used even if the SIP signaling used to control the call is not over TLS.

=== SIP ===

 '''Account.sip.outbound_proxy''' (type={{{SIPProxy}}}, default={{{None}}}, nillable={{{True}}})::

  This setting specifies whether to send all SIP requests when creating a new SIP dialog to a specific proxy. If this setting is set to {{{None}}}, then an RFC3263 lookup will be done based on the domain part of the SIP request URI.

 '''Account.sip.register''' (type={{{bool}}}, default={{{True}}})::

  If this setting is set to {{{True}}}, the Account will automatically register when it is active. More about this is described in [wiki:SipMiddlewareApi#Account Account].

 '''Account.sip.publish_interval''' (type={{{NonNegativeInteger}}}, default={{{600}}})::

  This setting controls the number of seconds used for the ''Expire'' header when publishing events. It must be a non-negative integer.

 '''Account.sip.subscribe_interval''' (type={{{NonNegativeInteger}}}, default={{{600}}})::

  This setting controls the number of seconds used for the ''Expire'' header when subscribing to events. It must be a non-negative integer.

 '''Account.registration.interval''' (type={{{NonNegativeInteger}}}, default={{{600}}})::

  This setting controls the number of seconds used for the ''Expire'' header when registering. It must be a non-negative integer.

=== TLS ===

 '''Account.tls.certificate''' (type={{{DataPath}}}, default={{{None}}}, nillable={{{True}}})::

  The path to the file that contains the certificate and its private key used to authenticate on TLS connections. If it is set to relative path, it is taken relative to {{{SIPSimpleSettings.data_directory}}}; otherwise it is interpreted as an absolute path. In order to access the full path to the history directory, the value attribute on the setting can be used:

  {{{

  Account.tls.certificate.value

  }}}

 '''Account.tls.verify_server''' (type={{{bool}}}, default={{{False}}})::

  If this setting is set to {{{True}}}, the middleware will verify the server's certificate when connecting via TLS.

=== XCAP  ===

 '''Account.xcap.enabled''' (type={{{bool}}}, default={{{True}}})::

  If this setting is set to {{{True}}}, The use of XCAP root set below will be activated.

 '''Account.xcap.xcap_root''' (type={{{XCAPRoot}}}, default={{{None}}}, nillable={{{True}}})::

  The XCAP root is required for accessing documents via the XCAP protocol. It must be a URL with either the ''http'' or ''https'' schemes.

 '''Account.xcap.use_xcap_diff''' (type={{{bool}}}, default={{{True}}})::

  If this setting is set to {{{True}}}, the Account will subscribe to the ''xcap-diff'' event in order to find out if the XCAP documents handled by the Account are modified by another entity.

== BonjourAccount ==

{{{

Account bonjour@local:

          +-- display_name = Bonjour User

account --|-- enabled = False

          |-- rtp

          +-- tls

      +-- audio_codec_list = None

rtp --|-- inband_dtmf = False

      |-- srtp_encryption = optional

      +-- use_srtp_without_tls = False

      +-- certificate = tls/bonjour@local.crt

tls --|-- verify_server = False

      +

}}}

The BonjourAccount is a singleton object as there can only be one bonjour account on a system. A bonjour account is used in P2P mode and does not interact with any server. Similar to the Account, it is used both as a complex object, which contains the required behavior for bonjour, as well as a container for the settings which apply to it. 

The settings of the BonjourAccount are described below:

 '''BonjourAccount.id''' (type={{{SIPAddress}}})::

  This is not a setting, as it is the static string 'bonjour@local' which represents the id of the BonjourAccount.

 '''BonjourAccount.enabled''' (type={{{bool}}}, default={{{True}}})::

  If this setting is set to {{{True}}}, the account will be used. More information about this is in [wiki:SipMiddlewareApi#BonjourAccount BonjourAccount].

 '''BonjourAccount.display_name''' (type={{{str}}}, default={{{None}}}, nillable={{{True}}})::

  The contents of this setting will be sent as part of the ''From'' header when sending SIP requests.

=== RTP ===

 '''BonjourAccount.rtp.audio_codec_list''' (type={{{AudioCodecs}}}, default={{{('speex', 'g722', 'g711', 'ilbc', 'gsm')}}})::

  This setting is used to specify the preferred audio codecs, which should be used for audio calls of this account. It must be a tuple containing only strings, which represent the supported codecs (speex, g722, g711, ilbc and gsm), in the order in which they are preferred.

 '''BonjourAccount.rtp.srtp_encryption''' (type={{{SRTPEncryption}}}, default={{{'optional'}}})::

  The value of this setting specifies how the account requires the calls to be encrypted using SRTP. It can be one of the values {{{'disabled'}}}, {{{'optional'}}} or {{{'mandatory'}}}.

 '''BonjourAccount.rtp.use_srtp_without_tls''' (type={{{bool}}}, default={{{False}}})::

  If this setting is set to {{{True}}}, SRTP could be used even if the SIP signaling used to control the call is not over TLS.

=== TLS ===

 '''Account.tls.certificate''' (type={{{DataPath}}}, default={{{None}}}, nillable={{{True}}})::

  The path to the file that contains the certificate and its private key used to authenticate on TLS connections. If it is set to relative path, it is taken relative to {{{SIPSimpleSettings.user_data_directory}}}; otherwise it is interpreted as an absolute path. In order to access the full path to the history directory, the value attribute on the setting can be used:

  {{{

  Account.tls.certificate.value

  }}}

 '''Account.tls.verify_server''' (type={{{bool}}}, default={{{False}}})::

  If this setting is set to {{{True}}}, the middleware will verify the server's certificate when connecting via TLS.

== SIPClients Settings Index ==

== General settings ==

 '''SIPSimpleSettings.user_data_directory''' (type={{{AbsolutePath}}}, default={{{'~/.sipclient}}})::

  This is the directory, which will be used by default for storing the SIP SIMPLE data. The relative paths are calculated on runtime based on this setting, which means that if this setting is changed, all relative paths will point inside the new directory. It is a string, which must be an absolute path.

=== Audio ===

 '''SIPSimpleSettings.audio.directory''' (type={{{DataPath}}}, default={{{DataPath('history')}}})::

  This directory will be used to store recorded audio conversations. Under this directory, a subdirectory per account with the id of the account as the name will be created. If it is set to relative path, it is taken relative to {{{SIPSimpleSettings.user_data_directory}}}; otherwise it is interpreted as an absolute path. In order to access the full path to the history directory, the value attribute on the setting can be used:

  {{{

  SIPSimpleSettings().audio.directory.value

  }}}

=== File Transfer ===

 '''SIPSimpleSettings.file_transfer.directory''' (type={{{DataPath}}}, default={{{DataPath('file_transfers')}}})::

  This directory is used to store the files obtained via MSRP file transfer. If it is set to relative path, it is taken relative to {{{SIPSimpleSettings.user_data_directory}}}; otherwise it is interpreted as an absolute path. In order to access the full path to the history directory, the value attribute on the setting can be used:

  {{{

  SIPSimpleSettings().file_transfer.directory.value

  }}}

=== Logs ===

 '''SIPSimpleSettings.logs.directory''' (type={{{DataPath}}}, default={{{DataPath('logs')}}})::

  This is the directory where the logs create by the SIP SIMPLE middleware will be stored. If it is set to relative path, it is taken relative to {{{SIPSimpleSettings.user_data_directory}}}; otherwise it is interpreted as an absolute path. In order to access the full path to the history directory, the value attribute on the setting can be used:

  {{{

  SIPSimpleSettings().logs.directory.value

  }}}

 '''SIPSimpleSettings.logs.trace_sip''' (type={{{bool}}}, default={{{False}}})::

  If this setting is set to True, the SIP packets will be written to a log file named 'sip_trace.txt', inside the directory pointed by {{{SIPSimpleSettings.logging.directory}}}.

 '''SIPSimpleSettings.logs.trace_pjsip''' (type={{{bool}}}, default={{{False}}})::

  If this setting is set to True, the PJSIP log messages will be written to a log file named 'pjsip_trace.txt', inside the directory pointed by {{{SIPSimpleSettings.logging.directory}}}.

 '''SIPSimpleSettings.logs.trace_msrp''' (type={{{bool}}}, default={{{False}}})::

  If this setting is set to True, the MSRP packets will be written to a log file named 'msrp_trace.txt', inside the directory pointed by {{{SIPSimpleSettings.logging.directory}}}.

 '''SIPSimpleSettings.logs.trace_xcap''' (type={{{bool}}}, default={{{False}}})::

  If this setting is set to True, the XCAP packets will be written to a log file named 'xcap_trace.txt', inside the directory pointed by {{{SIPSimpleSettings.logging.directory}}}.

=== Sounds ===

 '''SIPSimpleSettings.sounds.audio_inbound''' (type={{{AbsolutePath}}}, default={{{None}}}, nillable={{{True}}})::

  This setting should point to a wav file, which will be played when a SIP session request is received. If it is set to {{{None}}}, no sound will be played.

 '''SIPSimpleSettings.sounds.audio_outbound''' (type={{{AbsolutePath}}}, default={{{None}}}, nillable={{{True}}})::

  This setting should point to a wav file, which will be used as ringtone during an outgoing SIP session request as a response to a 180 Ringing. If it is set to {{{None}}}, no sound will be played.

 '''SIPSimpleSettings.sounds.file_sent''' (type={{{AbsolutePath}}}, default={{{None}}}, nillable={{{True}}})::

  This setting should point to a wav file, which will be played when an outgoing file transfer is finished. If it is set to {{{None}}}, no sound will be played.

 '''SIPSimpleSettings.sounds.file_received''' (type={{{AbsolutePath}}}, default={{{None}}}, nillable={{{True}}})::

  This setting should point to a wav file, which will be played when an incoming file transfer is finished. If it is set to {{{None}}}, no sound will be played.

 '''SIPSimpleSettings.sounds.message_sent''' (type={{{AbsolutePath}}}, default={{{None}}}, nillable={{{True}}})::

  This setting is a string representing an absolute path to a wav file, which is played when a message is sent in a chat session. If it is set to {{{None}}}, no sound is played.

 '''SIPSimpleSettings.sounds.message_received''' (type={{{AbsolutePath}}}, default={{{None}}}, nillable={{{True}}})::

  This setting is a string representing an absolute path to a wav file, which is played when a message is received in a chat session. If it is set to {{{None}}}, no sound is played.

== Account ==

=== Sounds ===

 '''Account.sounds.audio_inbound''' (type={{{AbsolutePath}}}, default={{{None}}}, nillable={{{True}}})::

  This setting should point to a wav file, which will be used to play the incoming ringtone. If it is set to {{{None}}}, the wav file set in {{{SIPSimpleSettings.sounds.audio_inbound}}} will be used instead.

== BonjourAccount ==

=== Sounds ===

 '''BonjourAccount.sounds.audio_inbound''' (type={{{AbsolutePath}}}, default={{{None}}}, nillable={{{True}}})::

  This setting should point to a wav file which will be used as the incoming ringtone. If it is set to {{{None}}}, the wav file set in {{{SIPSimpleSettings.sounds.audio_inbound}}} will be used instead.

== Architecture ==

Configuration API consists of the low-level classes that can be used for storing and retrieving configuration objects. Moreover, it allows the creation of a higher level API for accessing configuration items. The SIP SIMPLE settings are defined using this API, however application-specific settings can also make use of it in order to define a consistent view of all the settings.

The module '''sipsimple.configuration''' contains the main classes of the configuration API. These are:

 * ConfigurationManager

 * SettingsObject

 * SettingsGroup

 * Setting

In addition, the exceptions which make up this package are:

 * ConfigurationError (base class for all other configuration errors)

 * DuplicateSectionError

 * UnknownSectionError

 * UnknownNameError

The package '''sipsimple.configuration.backend''' contains the abstract interface for configuration backends, as well as concrete implementations of backends. This package is explained in more detail in [wiki:SipConfigurationAPI#ConfigurationBackendAPI Configuration Backend API].

=== Configuration Manager ===

The central entity is the ConfigurationManager, which is used for storing and retrieving configuration objects. Each stored configuration object has an associated name and a section, which allows similar objects or objects of the same type to be grouped together under the same section. Note that the names of the objects need to be unique inside a section. A pluggable backend system explained in [wiki:SipConfigurationAPI#ConfigurationBackendAPI Configuration Backend API] allows the configuration to be stored using any format, which can store (name, value) string pairs in sections.

The ConfigurationManager class is a singleton to allow any part of the code to access it without the need to pass references. However, its '''start''' method needs to be called before it can be used. Once this is done, objects can be added, retrieved or deleted from the underlying storage. The methods of ConfigurationManager are:

 '''!__init!__'''(''self'')::

 References to the ConfigurationManager instance can be obtained anytime without passing any arguments. However, it needs the manager needs to be started in order to be used, otherwise all methods will raise a RuntimeError.

 '''start'''(''self'', '''backend'''={{{None}}})::

 The start method allows the ConfigurationManager instance to use the specified backend for accessing the underlying storage. If a backend is not provided, then a {{{sipsimple.configuration.backend.configfile.ConfigFileBackend}}} instance will be created, without passing any arguments to the constructor. See [wiki:SipConfigurationAPI#ConfigFileBackend ConfigFileBackend] for information on how this object stores the data.

 '''set'''(''self'', '''section''', '''name''', '''object''')::

 The {{{object}}} will be sent to the configuration backend for storing, under {{{section}}}, with the specified {{{name}}}. If there already was an object with that name, it will be overwritten. If the section did not exist, then it will be created first. Note that changes are not guaranteed to have been written to the underlying storage until the '''save''' method is called.

 '''delete'''(''self'', '''section''', '''name''')::

 If an object stored as {{{name}}} exists in {{{section}}}, then it will be deleted. If the section was never created, then an {{{UnknownSectionError}}} will be raised.

 '''get'''(''self'', '''section''', '''name''')::

 Retrieves the object stored with {{{name}}} in {{{section}}}, if it exists. Otherwise, the method will raise an {{{UnknownSectionError}}} or an {{{UnknownNameError}}} if the section or name do not exist.

 '''get_names'''(''self'', '''section''')::

 Returns a list with all the names of the objects in {{{section}}}. Will raise {{{UnknownSectionError}}} if the section does not exist.

 '''save'''(''self'')::

 Flushes the changes made to the configuration to disk. This method must be called to ensure that all changes have been written.

The notifications of the ConfigurationManager are:

 '''CFGManagerSaveFailed'''::

 This notification is sent when a SettingsObject needs to be stored to the persisent storage, but the process fails. The attributes of it are:

 [[BR]]''exception'':[[BR]]

 The exception which was raised when the storing failed.

 [[BR]]''modified'':[[BR]]

 This attribute is only set if the storage process was started as a result of calling the save method on the SettingsObject. It's contents is the same as for the {{{CFGSettingsObjectDidChange}}} notification.

=== SettingsObject ===

A SettingsObject is used to represent a hierarchy of settings, which are managed via the ConfigurationManager. There are two types of SettingsObject:

 * pure Singleton SettingsObjects, i.e. there is only one instance of this SettingsObject in an application. This also means that the object cannot be deleted. An example of such a SettingsObject is SIPSimpleSettings. These SettingsObjects are useful to represent global settings.

 * SettingsObject with an associated id. These are Singleton as well, but there is more than one instance: one per id. The instances are not necessarily persistent. New ones can be created and existing ones can be deleted. An example of such a SettingsObject is the Account. These SettingsObjects are useful to represent settings which apply to entities identifiable by a string id.

All SettingsObjects belong to a specific section, specified using the {{{__section__}}} attribute.

When a SettingsObject is instantiated its contained settings are loaded from the configuration storage. If it is the first time a SettingsObject is created, the default values for the settings will apply. The SettingsObject will only be copied to storage when its '''save''' method is called.

==== Defining a global SettingsObject ====

In order to define a global SettingsObject, the {{{__section__}}} and {{{__id__}}} attributes must be defined on the class. The {{{__id__}}} must not be used in any other SettingsObject which is stored in the same section. An example of defining a global SettingsObject:

{{{

from sipsimple.configuration import SettingsObject

class SIPSimpleSettings(SettingsObject):

    __section__ = 'Global'

    __id__ = 'SIPSimple'

}}}

The {{{__init__}}} method must not accept any other argument except ''self''. It will be called each time the settings are loaded from the storage, not only the first time the object is created.

==== Defining a per-id SettingsObject ====

In order to define a per-id SettingsObject, the {{{__section__}}} attribute must be defined on the class, while the {{{__id__}}} attribute must be left to None. When instantiating the resulting class, exactly one argument must be given, which represents the string id. Each class defined as a per-id SettingsObject must be allocated a different section from all the other SettingsObjects (including global ones), otherwise the keys under which the SettingsObjects are stored could overlap. An example of defining a per-id SettingsObject:

{{{

from sipsimple.configuration import SettingsObject

class Account(SettingsObject):

    __section__ = 'Accounts'

    def __init__(self, id):

        """Do something each time the Account is loaded"""

}}}

The {{{__init__}}} method must accept exactly one argument except ''self''. It will be called each time the object is loaded from the storage, in addition to the first time the object is created. This allows the SettingsObject to be more than a simple collection of settings.

==== Instance methods of SettingsObjects ====

 '''save'''(''self'')::

 If the contained Settings of this SettingsObject have changed, the object will be saved to the persistent storage. A CFGSettingsObjectDidChange notification will be issued which contains the modified settings. If the save fails, a CFGManagerSaveFailed notification is issued in addition.

 '''delete'''(''self'')::

 This method can only be called on per-id SettingsObjects. It will delete the object from the persistent storage. All references to this SettingsObject must be removed.

==== Notifications ====#SettingsObjectNotifications

 '''CFGSettingsObjectDidChange'''::

 This notification is sent when the save method of a SettingsObject is called. Attributes:

 [[BR]]''modified'':[[BR]]

 A dict instance which maps settings keys in their fully qualified form (attribute names seperated by '.', relative to the SettingsObject) to a ModifiedValue instance; the ModifiedValue instance contains two attributes: ''old'' and ''new'' which are set to the old and the new Setting's value respectively.

=== Setting ===

The Setting descriptor is used to describe a setting in SettingsObjects. The following methods are part of the public API of it:

 '''!__init!__'''(''self'', '''type''', '''default'''={{{None}}}, '''nillable'''={{{False}}})::

 Create a new Setting descriptor which represents a setting in all instances of a SettingsObject. The default value must be specified if the setting is not nillable. The type will be applied to the values which are set to this descriptor if the value is not already an instance of the type.

An example of using a setting:

{{{

from sipsimple.configuration import Setting, SettingsObject

class SIPSimpleSettings(SettingsObject):

    __section__ = 'Global'

    __id__ = 'SIPSimple'

    user_agent = Setting(type=str, default='sipsimple %s' % __version__)

}}}

=== SettingsGroup ===

A SettingsGroup allows settings to be structured hierarchically. Subclasses of SettingsGroup are containers for Settings and other SettingsGroups just as SettingsObjects are. In addition, the subclasses of SettingsGroup are descriptors and can be used as such to assign a SettingsGroup as a child of another SettingsGroup or a SettingsObject. An example usage containing Setting, SettingsGroup and SettingsObject:

{{{

from sipsimple.configuration import Setting, SettingsGroup, SettingsObject

class TLSSettings(SettingsGroup):

    verify_server = Setting(type=bool, default=False)

class SIPSimpleSettings(SettingsObject):

    __section__ = 'Global'

    __id__ = 'SIPSimple'

    user_agent = Setting(type=str, default='sipsimple %s' % __version__)

    tls = TLSSettings

}}}

=== Backend API ===

The backend API provides a way to use the configuration framework consistently, while using any system for storing the data persistently. The ConfigurationManager makes use of a backend whenever it needs to write/read something to the persistent storage. The backend only needs to know how to handle (key, value) string pairs in sections. In order to use a specific backend, it is given to the ConfigurationManager in its start method.

The interface '''sipsimple.configuration.backend.IBackend''' describes the backend:

 '''add_section'''('''section''')::

 Add a section with a specified name or raise DuplicateSectionError if the section already exists.

 '''delete_section'''('''section''')::

 Delete a section identified by a name or raise UnknownSectionError if the section does not exist.

 '''set'''('''section''', '''name''', '''value''')::

 Set a name, value pair inside a section. Will overwrite the previous pair, if it exists; otherwise raise UnknownSectionError if the section does not exist.

 '''delete'''('''section''', '''name''')::

 Delete a name, value pair from a section or raise UnknownSectionError if the section does not exist.

 '''get'''('''section''', '''name''')::

 Get the value associated to the name, in the specified section or raise UnknownNameError if such a name, value pair does not exist and UnknownSectionError if the section does not exist.

 '''get_names'''('''section''')::

 Get all the names from  the specified section or raise UnknownSectionError if the section does not exist.

 '''save'''()::

 Flush the modified name, value pairs.

==== ConfigFileBackend ====

A concrete implementation of the '''IBackend''' interface resides in '''sipsimple.configuration.backend.configfile.ConfigFileBackend'''. The methods different from the ones in '''IBackend''' are:

 '''!__init!__'''(''self'', '''filename'''={{{None}}})::

 Create a new ConfigFileBackend which uses the specified filename for loading and storing the data to. If it is not given, it defaults to {{{~/.sipclient/config}}}.

===