SipConfigurationAPI

Version 65 (Anonymous, 06/28/2011 04:52 pm)

1 1 Adrian Georgescu
= Configuration API =
2 1 Adrian Georgescu
3 41 Adrian Georgescu
[[TOC(SipMiddlewareApi, SipConfigurationAPI, SipCoreApiDocumentation, depth=3)]]
4 1 Adrian Georgescu
5 28 Luci Stanescu
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. In addition, the configuration API offers an extensibility framework, by which applications can add their specific settings which will be managed in the same way as the middleware settings. The settings are loaded and saved from/to persistent storage using a backend; a backend is provided which has a simple text file format.
6 1 Adrian Georgescu
7 33 Luci Stanescu
The settings can be managed by API calls. The middleware settings have appropriate defaults so that it can function properly with a minimum amount of changes.
8 1 Adrian Georgescu
9 33 Luci Stanescu
== Architecture ==
10 33 Luci Stanescu
11 33 Luci Stanescu
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, by either extending the settings objects defined in the middleware or creating new settings objects.
12 33 Luci Stanescu
13 33 Luci Stanescu
The module '''sipsimple.configuration''' contains the main classes of the configuration API. These are:
14 33 Luci Stanescu
15 33 Luci Stanescu
 * ConfigurationManager
16 33 Luci Stanescu
 * SettingsObject
17 33 Luci Stanescu
 * SettingsGroup
18 33 Luci Stanescu
 * Setting
19 33 Luci Stanescu
 * SettingsObjectExtension
20 33 Luci Stanescu
21 33 Luci Stanescu
In addition, the exceptions which make up this package are:
22 33 Luci Stanescu
23 33 Luci Stanescu
 * ConfigurationError (base class for all other configuration errors)
24 33 Luci Stanescu
 * ObjectNotFoundError
25 33 Luci Stanescu
26 39 Adrian Georgescu
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#BackendAPI Configuration Backend API].
27 33 Luci Stanescu
28 37 Adrian Georgescu
=== ConfigurationManager ===
29 33 Luci Stanescu
30 33 Luci Stanescu
The central entity is the ConfigurationManager, which is used for storing and retrieving settings. Within the ConfigurationManager, settings can be represented in a hierarchical structure, where the root the of tree is the configuration ''document''. This structure is represented using a dictionary, defined recursively as:
31 33 Luci Stanescu
 * the keys of the dictionary are unicode objects
32 33 Luci Stanescu
 * the values of the dictionary can be:
33 33 Luci Stanescu
   * the None object (this represents a default value)
34 33 Luci Stanescu
   * unicode objects
35 33 Luci Stanescu
   * lists of unicode objects
36 33 Luci Stanescu
   * dictionaries using this specification
37 60 Adrian Georgescu
An item in the dictionary with an unicode object or a list as the value is a single setting: the name of the item is the name of the setting. An item with a dictionary as the value is a group of settings: the name of the item is the name of the group. This dictionary representation is stored to a persistent storage and loaded using the configuration backend as explained in [wiki:SipConfigurationAPI#ConfigurationBackendAPI Configuration Backend API]. Any backend which is able to store and load such data can be used. A simple [wiki:SipConfigurationAPI#FileBackend text file backend] and a [wiki:SipConfigurationAPI#MemoryBackend volatile memory backend] are provided. After configuration data is loaded from the backend, it is saved on the ConfigurationManager and can be managed using its methods; in order to save the data using the backend provided, the {{{save}}} method needs to be called; any calls to {{{update}}} or {{{delete}}} will not ask the backend to store the data as well.
38 33 Luci Stanescu
39 33 Luci Stanescu
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; if using the [wiki:SipMiddlewareApi#SIPApplication SIPApplication] class, its start method takes care of this passing as the backend the one it receives as an argument. The methods of ConfigurationManager are:
40 33 Luci Stanescu
41 33 Luci Stanescu
 '''!__init!__'''(''self'')::
42 33 Luci Stanescu
 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.
43 59 Adrian Georgescu
 '''start'''(''self'')::
44 59 Adrian Georgescu
 The start method allows the ConfigurationManager instance to use the backend specified in {{{SIPApplication}}} complying to the {{{Storage API}}} for accessing the underlying storage. See [wiki:SipConfigurationAPI#ConfigurationBackendAPI Configuration Backend API] for information on what the required interface for the passed object is. Raises a {{{ConfigurationBackendError}}} if the backend cannot load the configuration data from persistent storage.
45 33 Luci Stanescu
 '''update'''(''self'', '''group''', '''name''', '''data''')::
46 33 Luci Stanescu
 The partial {{{data}}} which must be a dictionary as formerly defined corresponding to an object having the specified name under the specified group. If {{{group}}} is {{{None}}}, the object will be saved top-level (its name will the a top-level key in the data dictionary). Note that changes will not be written to the underlying storage until the '''save''' method is called.
47 33 Luci Stanescu
 '''delete'''(''self'', '''group''', '''name''')::
48 33 Luci Stanescu
 If an object stored as {{{name}}} exists in {{{group}}}, then it will be deleted. If {{{group}}} is {{{None}}}, then the top-level object identified by {{{name}}} will be deleted.
49 33 Luci Stanescu
 '''get'''(''self'', '''group''', '''name''')::
50 33 Luci Stanescu
 Retrieves the object stored with {{{name}}} in {{{group}}}, if it exists. Otherwise, the method will raise an {{{ObjectNotFoundError}}}. If {{{group}}} is {{{None}}}, the top-level object identified by {{{name}}} will be retrieved.
51 33 Luci Stanescu
 '''get_names'''(''self'', '''group''')::
52 33 Luci Stanescu
 Returns a list with all the names of the objects in {{{group}}}. Returns an empty list if the group does not exist.
53 33 Luci Stanescu
 '''save'''(''self'')::
54 33 Luci Stanescu
 Flushes the changes made to the configuration to the backend. This method must be called to ensure that all changes have been written to persistent storage. Raises a {{{ConfigurationBackendError}}} if the backend cannot store the data to persistent storage. 
55 33 Luci Stanescu
56 33 Luci Stanescu
57 33 Luci Stanescu
=== SettingsObject ===
58 33 Luci Stanescu
59 33 Luci Stanescu
A SettingsObject is used to represent a hierarchy of settings, which are managed via the ConfigurationManager. There are two types of SettingsObject:
60 61 Adrian Georgescu
 * SettingsObjects without an ID, i.e. there should be only one instance of this SettingsObject in an application. When a subclass fo SettingsObject lacks a {{{__id__}}} attribute, that is, it doesn't have an ID it is automatically a {{{Singleton}}}. 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.
61 46 Luci Stanescu
 * SettingsObjects with an associated 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. The ID can be changed, which means these objects cannot be Singletons.
62 33 Luci Stanescu
63 33 Luci Stanescu
SettingsObjects can belong to a group, depending on whether the {{{__group__}}} attribute was specified. If it wasn't, the data will be saved top-level using the id of the SettingsObject; otherwise, the data will be saved under the group specified using the id. It is recommended that SettingsObjects with instances per id be saved in a group, although this is not enforced. For example, the Account instances are saved in a group named '''Accounts'''.
64 33 Luci Stanescu
65 62 Adrian Georgescu
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. If a SetttingsObject is deleted (by calling its '''delete''' method) it can no longer be saved, al subsequent calls to '''save''' will do nothing.
66 33 Luci Stanescu
67 33 Luci Stanescu
==== Defining a global SettingsObject ====
68 33 Luci Stanescu
69 1 Adrian Georgescu
In order to define a global SettingsObject, the {{{__id__}}} attribute must be defined on the class, while the {{{__group__}}} attribute can be defined. The {{{__id__}}} must not be used in any other SettingsObject which is stored in the same group (or globally if the {{{__group__}}} attribute is missing). An example of defining a global SettingsObject:
70 33 Luci Stanescu
{{{
71 33 Luci Stanescu
from sipsimple.configuration import SettingsObject
72 1 Adrian Georgescu
73 46 Luci Stanescu
class SIPSimpleSettings(SettingsObject):
74 33 Luci Stanescu
    __group__ = 'Global'
75 33 Luci Stanescu
    __id__ = 'SIPSimple'
76 33 Luci Stanescu
}}}
77 33 Luci Stanescu
78 33 Luci Stanescu
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.
79 33 Luci Stanescu
80 33 Luci Stanescu
81 33 Luci Stanescu
==== Defining a per-id SettingsObject ====
82 33 Luci Stanescu
83 33 Luci Stanescu
In order to define a per-id SettingsObject, the {{{__group__}}} attribute should 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 should be allocated a different group 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:
84 33 Luci Stanescu
{{{
85 33 Luci Stanescu
from sipsimple.configuration import SettingsObject
86 33 Luci Stanescu
87 33 Luci Stanescu
class Account(SettingsObject):
88 33 Luci Stanescu
    __group__ = 'Accounts'
89 33 Luci Stanescu
    def __init__(self, id):
90 33 Luci Stanescu
        """Do something each time the Account is loaded"""
91 33 Luci Stanescu
}}}
92 33 Luci Stanescu
93 33 Luci Stanescu
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.
94 33 Luci Stanescu
95 44 Adrian Georgescu
==== methods ====
96 33 Luci Stanescu
97 33 Luci Stanescu
 '''save'''(''self'')::
98 33 Luci Stanescu
 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.
99 33 Luci Stanescu
 '''delete'''(''self'')::
100 33 Luci Stanescu
 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.
101 44 Adrian Georgescu
102 1 Adrian Georgescu
==== notifications ====
103 33 Luci Stanescu
104 65 Adrian Georgescu
 '''CFGManagerSaveFailed'''::
105 65 Adrian Georgescu
 This notification is sent when the save or delete method of a SettingsObject fail to save the data in the configuration manager storage backend. Attributes:
106 65 Adrian Georgescu
 [[BR]]''modified'':[[BR]]
107 65 Adrian Georgescu
 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. If the object was never saved before, it will be None.
108 65 Adrian Georgescu
 [[BR]]''exception'':[[BR]]
109 65 Adrian Georgescu
 The exception object that was raised while attempting to save the data in the configuration manager.
110 65 Adrian Georgescu
 [[BR]]''operation'':[[BR]]
111 65 Adrian Georgescu
 Attempted opperation, one of 'save' or 'delete'.
112 65 Adrian Georgescu
 [[BR]]''timestamp'':[[BR]]
113 65 Adrian Georgescu
 A {{{datetime.datetime}}} object representing the moment the notification was sent.
114 65 Adrian Georgescu
115 33 Luci Stanescu
 '''CFGSettingsObjectDidChange'''::
116 63 Adrian Georgescu
 This notification is sent when the save method of a SettingsObject is called and some settings were previously changed. It will not be sent the first time {{{save}}} is called in an object. Attributes:
117 1 Adrian Georgescu
 [[BR]]''modified'':[[BR]]
118 1 Adrian Georgescu
 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.
119 46 Luci Stanescu
 [[BR]]''timestamp'':[[BR]]
120 46 Luci Stanescu
 A {{{datetime.datetime}}} object representing the moment the notification was sent.
121 57 Adrian Georgescu
122 1 Adrian Georgescu
 '''CFGSettingsObjectWasCreated'''::
123 63 Adrian Georgescu
 This notification is sent after a SettingsObject representing a configuration entity was saved for the first time. This notification will not be sent for global SettingsObject objects because they are never created, they always exist. Attributes:
124 63 Adrian Georgescu
 [[BR]]''timestamp'':[[BR]]
125 63 Adrian Georgescu
 A {{{datetime.datetime}}} object representing the moment the notification was sent.
126 63 Adrian Georgescu
127 63 Adrian Georgescu
 '''CFGSettingsObjectWasActivated'''::
128 63 Adrian Georgescu
 For global SettingsObject objects this notification is sent after the single object instance is created. For dynamic ID SettingsObject objects, this notification is sent when the object has been loaded from the configuration manager (if the object existed) or the first time {{{save}}} is called on a new object. Attributes:
129 57 Adrian Georgescu
 [[BR]]''timestamp'':[[BR]]
130 57 Adrian Georgescu
 A {{{datetime.datetime}}} object representing the moment the notification was sent.
131 57 Adrian Georgescu
132 57 Adrian Georgescu
 '''CFGSettingsObjectWasDeleted'''::
133 57 Adrian Georgescu
 This notification is sent after a SettingsObject has been deleted. Attributes:
134 57 Adrian Georgescu
 [[BR]]''timestamp'':[[BR]]
135 57 Adrian Georgescu
 A {{{datetime.datetime}}} object representing the moment the notification was sent.
136 57 Adrian Georgescu
137 33 Luci Stanescu
=== Setting ===
138 33 Luci Stanescu
139 33 Luci Stanescu
The Setting descriptor is used to describe a setting in SettingsObjects. The following methods are part of the public API of it:
140 33 Luci Stanescu
 '''!__init!__'''(''self'', '''type''', '''default'''={{{None}}}, '''nillable'''={{{False}}})::
141 1 Adrian Georgescu
 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; it is not applied to the default value.
142 33 Luci Stanescu
143 33 Luci Stanescu
An example of using a setting:
144 33 Luci Stanescu
{{{
145 1 Adrian Georgescu
from sipsimple import __version__
146 42 Luci Stanescu
from sipsimple.configuration import Setting, SettingsObject
147 33 Luci Stanescu
148 33 Luci Stanescu
class SIPSimpleSettings(SettingsObject):
149 33 Luci Stanescu
    __group__ = 'Global'
150 33 Luci Stanescu
    __id__ = 'SIPSimple'
151 33 Luci Stanescu
152 33 Luci Stanescu
    user_agent = Setting(type=str, default='sipsimple %s' % __version__)
153 33 Luci Stanescu
}}}
154 33 Luci Stanescu
155 33 Luci Stanescu
When a setting value is read from the configuration backend, the type is used to reconstruct the value from a unicode object, a list of unicode objects, or a dictionary containing unicode keys and values with any of these three types. Several built-in types are recognised and are handled automatically:
156 33 Luci Stanescu
 * bool: the unicode strings {{{u'yes'}}}, {{{u'true', {{{u'on'}}} and {{{u'1'}}} are considered to have the value {{{True}}}, while {{{u'no'}}}, {{{u'false'}}}, {{{u'off'}}} and {{{u'0'}}} are considered to have the value False; the comparison is done case insensitively; all other strings are considered invalid.
157 33 Luci Stanescu
 * int, long and basestring: the type is called using the value as an argument.
158 33 Luci Stanescu
All other types are instantiated using an un-pickling like mechanism. The {{{__new__}}} method is called without any arguments and {{{__setstate__}}} is called on the object returned by {{{__new__}}} using the value as the sole argument.
159 33 Luci Stanescu
160 33 Luci Stanescu
Saving a setting value is done similarly, according to type. The builtin types which are handled are the same:
161 33 Luci Stanescu
 * bool: the unicode objects {{{u'true'}}} and {{{u'false}}} are used depending on the value.
162 33 Luci Stanescu
 * int, long and basestring: {{{unicode}}} is called with the value as the sole argument.
163 33 Luci Stanescu
For all other types, the {{{__getstate__}}} method is called which should return an appropriate value.
164 33 Luci Stanescu
165 33 Luci Stanescu
166 1 Adrian Georgescu
=== SettingsGroup ===
167 33 Luci Stanescu
168 33 Luci Stanescu
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:
169 33 Luci Stanescu
{{{
170 42 Luci Stanescu
from sipsimple import __version__
171 33 Luci Stanescu
from sipsimple.configuration import Setting, SettingsGroup, SettingsObject
172 33 Luci Stanescu
173 1 Adrian Georgescu
class TLSSettings(SettingsGroup):
174 33 Luci Stanescu
    verify_server = Setting(type=bool, default=False)
175 33 Luci Stanescu
176 33 Luci Stanescu
class SIPSimpleSettings(SettingsObject):
177 33 Luci Stanescu
    __group__ = 'Global'
178 33 Luci Stanescu
    __id__ = 'SIPSimple'
179 33 Luci Stanescu
180 33 Luci Stanescu
    user_agent = Setting(type=str, default='sipsimple %s' % __version__)
181 33 Luci Stanescu
182 33 Luci Stanescu
    tls = TLSSettings
183 33 Luci Stanescu
}}}
184 33 Luci Stanescu
185 1 Adrian Georgescu
=== SettingsObjectExtension ===
186 33 Luci Stanescu
187 33 Luci Stanescu
The SettingsObjectExtension allows an application to add or customize the settings of the middleware according to its needs. In order to add or replace settings/settings groups defined in another SettingsObject, SettingsObjectExtension can be subclassed and the register_extension class method of the original SettingsObject can be called passing the SettingObjectExtension subclass as the sole argument. In order to add/replace settings in a group of settings, the original SettingsGroup can be subclassed. Example:
188 33 Luci Stanescu
{{{
189 42 Luci Stanescu
from sipsimple import __version__
190 42 Luci Stanescu
from sipsimple.configuration import Setting, SettingsGroup, SettingsObject, SettingsObjectExtension
191 33 Luci Stanescu
192 1 Adrian Georgescu
class TLSSettings(SettingsGroup):
193 33 Luci Stanescu
    verify_server = Setting(type=bool, default=False)
194 33 Luci Stanescu
195 33 Luci Stanescu
class SIPSimpleSettings(SettingsObject):
196 33 Luci Stanescu
    __group__ = 'Global'
197 33 Luci Stanescu
    __id__ = 'SIPSimple'
198 33 Luci Stanescu
199 33 Luci Stanescu
    user_agent = Setting(type=str, default='sipsimple %s' % __version__)
200 33 Luci Stanescu
201 33 Luci Stanescu
    tls = TLSSettings
202 33 Luci Stanescu
203 33 Luci Stanescu
class TLSSettingsExtension(TLSSettings):
204 33 Luci Stanescu
    verify_client = Setting(type=bool, default=True)
205 33 Luci Stanescu
206 33 Luci Stanescu
class SIPSimpleSettingsExtension(SettingsObjectExtension):
207 33 Luci Stanescu
    default_account = Setting(type=str, default=None, nillable=True)
208 33 Luci Stanescu
209 33 Luci Stanescu
    tls = TLSSettingsExtension
210 33 Luci Stanescu
211 33 Luci Stanescu
SIPSimpleSettings.register_extension(SIPSimpleSettingsExtension)
212 33 Luci Stanescu
}}}
213 33 Luci Stanescu
214 33 Luci Stanescu
=== Backend API ===
215 33 Luci Stanescu
216 33 Luci Stanescu
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 data in the dictionary format explained in [wiki:SipConfigurationAPI#ConfigurationManager Configuration Manager]. In order to use a specific backend, it is given to the ConfigurationManager in its start method.
217 33 Luci Stanescu
218 33 Luci Stanescu
The interface '''sipsimple.configuration.backend.IBackend''' describes the backend:
219 33 Luci Stanescu
 '''load'''()::
220 33 Luci Stanescu
 Load the configuration data using whatever means employed by the backend implementation and return a dictionary conforming to the definition in [wiki:SipConfigurationAPI#ConfigurationManager Configuration Manager].
221 33 Luci Stanescu
 '''save'''('''data''')::
222 33 Luci Stanescu
 Given a dictionary conforming to the definition in this interface, save the data using whatever means employed by the backend implementation.
223 33 Luci Stanescu
224 33 Luci Stanescu
225 33 Luci Stanescu
==== FileBackend ====
226 33 Luci Stanescu
227 33 Luci Stanescu
A concrete implementation of the '''IBackend''' interface resides in '''sipsimple.configuration.backend.file.FileBackend'''. The methods different from the ones in '''IBackend''' are:
228 33 Luci Stanescu
229 33 Luci Stanescu
 '''!__init!__'''(''self'', '''filename''', '''encoding'''={{{'utf-8'}}})::
230 33 Luci Stanescu
 Create a new FileBackend which uses the specified filename for loading and storing the data to; the data is written using the specified encoding, defaulting to UTF-8.
231 33 Luci Stanescu
232 33 Luci Stanescu
This object saves the data using a simple text file format with the following syntax:
233 33 Luci Stanescu
 * SettingGroups, SettingsObjects or Groups of SettingsObjects are represented by their name (or id in the case of SettingsObjects) followed by a colon (''':'''). These containers can contain other such containers or simple settings. Their children need to be indented more that the container itself. The indentation need not be consistent.
234 33 Luci Stanescu
 {{{
235 33 Luci Stanescu
 Accounts:
236 33 Luci Stanescu
    user@domain:
237 33 Luci Stanescu
      display_name = User
238 33 Luci Stanescu
      tls:
239 33 Luci Stanescu
        certificate =
240 33 Luci Stanescu
 }}}
241 33 Luci Stanescu
 * Simple settings are represented by a name followed by an equals sign and the value; whitespace anywhere in between is ignored. The different values are represented in the following way:
242 33 Luci Stanescu
  * None is represented by the absence of a value.
243 33 Luci Stanescu
  {{{
244 33 Luci Stanescu
    setting =
245 33 Luci Stanescu
  }}}
246 33 Luci Stanescu
  * Unicode objects are represented by a simple string (which can be quoted to include leading and trailing whitespace by either single or double quotes) and can have the following espace sequances: '''\' ''', '''\"''', '''\n''', '''\r'''. The unicode characters are encoded using the encoding specified in the constructor.
247 33 Luci Stanescu
  {{{
248 33 Luci Stanescu
    setting1 = value
249 33 Luci Stanescu
    setting2 = value with spaces
250 33 Luci Stanescu
    setting3 = "  value with leading and trailing spaces  "
251 33 Luci Stanescu
    setting4 = value with a line feed\n
252 33 Luci Stanescu
  }}}
253 33 Luci Stanescu
  * Lists are represented by unicode strings as described above separated by commas (''','''). Any not-quoted whitespace around the comma is ignored.
254 33 Luci Stanescu
  {{{
255 33 Luci Stanescu
    setting = a, b  , c
256 33 Luci Stanescu
  }}}
257 33 Luci Stanescu
  * Complex settings can be represented just like a group:
258 33 Luci Stanescu
  {{{
259 33 Luci Stanescu
    complex_setting:
260 33 Luci Stanescu
      field1 = value
261 33 Luci Stanescu
      field2 = 123
262 33 Luci Stanescu
  }}}
263 1 Adrian Georgescu
  
264 60 Adrian Georgescu
==== MemoryBackend ====
265 60 Adrian Georgescu
266 60 Adrian Georgescu
A concrete implementation of the '''IBackend''' interface resides in '''sipsimple.configuration.backend.memory.MemoryBackend'''.
267 60 Adrian Georgescu
268 33 Luci Stanescu
269 35 Luci Stanescu
== Middleware Settings ==
270 4 Adrian Georgescu
271 4 Adrian Georgescu
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].
272 1 Adrian Georgescu
273 1 Adrian Georgescu
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}}}.
274 4 Adrian Georgescu
275 33 Luci Stanescu
=== General ===
276 1 Adrian Georgescu
277 22 Adrian Georgescu
{{{
278 22 Adrian Georgescu
SIP SIMPLE settings:
279 27 Luci Stanescu
             +-- default_account = user@example.com
280 48 Adrian Georgescu
SIP SIMPLE --|-- user_agent = sipsimple 0.16.2
281 22 Adrian Georgescu
             |-- audio
282 4 Adrian Georgescu
             |-- chat
283 22 Adrian Georgescu
             |-- desktop_sharing
284 1 Adrian Georgescu
             |-- file_transfer
285 23 Adrian Georgescu
             |-- logs
286 1 Adrian Georgescu
             |-- rtp
287 17 Adrian Georgescu
             |-- sip
288 48 Adrian Georgescu
             |-- sounds
289 1 Adrian Georgescu
             +-- tls
290 1 Adrian Georgescu
291 1 Adrian Georgescu
        +-- alert_device = system_default
292 48 Adrian Georgescu
audio --|-- input_device = system_default                   
293 17 Adrian Georgescu
        |-- output_device = system_default
294 1 Adrian Georgescu
        |-- sample_rate = 44100
295 1 Adrian Georgescu
        |-- silent = False
296 48 Adrian Georgescu
        +-- tail_length = 0
297 27 Luci Stanescu
298 1 Adrian Georgescu
       +
299 23 Adrian Georgescu
chat --|
300 23 Adrian Georgescu
       +
301 22 Adrian Georgescu
302 17 Adrian Georgescu
                  +
303 17 Adrian Georgescu
desktop_sharing --|
304 22 Adrian Georgescu
                  +
305 23 Adrian Georgescu
306 1 Adrian Georgescu
                +
307 18 Adrian Georgescu
file_transfer --|
308 22 Adrian Georgescu
                +
309 1 Adrian Georgescu
310 48 Adrian Georgescu
logs --|-- pjsip_level = 5
311 1 Adrian Georgescu
312 48 Adrian Georgescu
      +-- audio_codec_list = AudioCodecList(['G722', 'PCMU', 'GSM', 'speex', 'PCMA'])
313 48 Adrian Georgescu
rtp --|-- port_range = PortRange(start=50000, end=50500)
314 1 Adrian Georgescu
      +-- timeout = 30
315 1 Adrian Georgescu
316 48 Adrian Georgescu
      +-- invite_timeout = 90
317 48 Adrian Georgescu
sip --|-- tcp_port = 0
318 48 Adrian Georgescu
      |-- tls_port = 0
319 1 Adrian Georgescu
      |-- transport_list = SIPTransportList(['tls', 'tcp', 'udp'])
320 1 Adrian Georgescu
      +-- udp_port = 0
321 1 Adrian Georgescu
322 49 Adrian Georgescu
      +-- ca_list = None
323 1 Adrian Georgescu
tls --|-- protocol = TLSv1
324 48 Adrian Georgescu
      +-- timeout = 3000
325 1 Adrian Georgescu
326 48 Adrian Georgescu
327 28 Luci Stanescu
}}}
328 28 Luci Stanescu
329 1 Adrian Georgescu
The {{{sipsimple.configuration.settings.SIPSimpleSettings}}} class is a singleton can be instantiated and used anywhere after the [wiki:SipConfigurationAPI#ConfigurationManager ConfigurationManager] has been started. 
330 28 Luci Stanescu
331 1 Adrian Georgescu
The settings are explained below:
332 28 Luci Stanescu
333 28 Luci Stanescu
 '''SIPSimpleSettings.default_account''' (type={{{str}}}, default={{{'bonjour@local'}}}, nillable={{{True}}})::
334 1 Adrian Georgescu
  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.
335 1 Adrian Georgescu
336 28 Luci Stanescu
 '''SIPSimpleSettings.user_agent''' (type={{{str}}}, default={{{'sipsimple VERSION'}}})::
337 28 Luci Stanescu
  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.
338 1 Adrian Georgescu
339 33 Luci Stanescu
==== Audio ====
340 17 Adrian Georgescu
341 48 Adrian Georgescu
 '''SIPSimpleSettings.audio.alert_device''' (type={{{AudioOutputDevice}}}, default={{{'system_default'}}}, nillable={{{True}}})::
342 48 Adrian Georgescu
  The name of the alert device, which can be used for alerting the user. If it is set to {{{'system_default'}}}, one will be selected automatically by the operating system; if it is set to {{{None}}}, a dummy device will be used which will discard any audio data. This device is not used by the middleware but is provided for consistency.
343 48 Adrian Georgescu
344 1 Adrian Georgescu
 '''SIPSimpleSettings.audio.input_device''' (type={{{AudioInputDevice}}}, default={{{'system_default'}}}, nillable={{{True}}})::
345 4 Adrian Georgescu
  The name of the audio device, which will be used for input (recording). If it is set to {{{'system_default'}}}, one will be selected automatically by the operating system; if it is set to {{{None}}}, a dummy device will be used which doesn't record anything.
346 24 Adrian Georgescu
347 1 Adrian Georgescu
 '''SIPSimpleSettings.audio.output_device''' (type={{{AudioOutputDevice}}}, default={{{'system_default'}}}, nillable={{{True}}})::
348 1 Adrian Georgescu
  The name of the audio device, which will be used for output (playback). If it is set to {{{'system_default'}}, one will be selected automatically by the operating system; if it is set to {{{None}}}, a dummy device will be used which will discard any audio data.
349 24 Adrian Georgescu
350 4 Adrian Georgescu
 '''SIPSimpleSettings.audio.tail_length''' (type={{{NonNegativeInteger}}}, default={{{200}}})::
351 27 Luci Stanescu
  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.
352 24 Adrian Georgescu
353 48 Adrian Georgescu
 '''SIPSimpleSettings.audio.sample_rate''' (type={{{SampleRate}}}, default={{{44100}}})::
354 1 Adrian Georgescu
  This is the sample rate at which the audio system runs, in Hz. 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 (if possible). Example values include 8000, 32000, 44100 etc.
355 1 Adrian Georgescu
 
356 1 Adrian Georgescu
 '''SIPSimpleSettings.audio.silent''' (type={{{bool}}}, default={{{False}}})::
357 1 Adrian Georgescu
  If this setting is set to True, no audio notifications will be played on the alert device (the volume of the alert device will be set to 0).
358 1 Adrian Georgescu
359 1 Adrian Georgescu
==== Chat ====
360 1 Adrian Georgescu
361 4 Adrian Georgescu
Empty section for future use.
362 1 Adrian Georgescu
363 1 Adrian Georgescu
==== Desktop Sharing ====
364 33 Luci Stanescu
365 1 Adrian Georgescu
Empty section for future use.
366 23 Adrian Georgescu
367 1 Adrian Georgescu
==== File Transfer ====
368 33 Luci Stanescu
369 1 Adrian Georgescu
Empty section for future use.
370 1 Adrian Georgescu
371 23 Adrian Georgescu
==== Logs ====
372 33 Luci Stanescu
373 1 Adrian Georgescu
 '''SIPSimpleSettings.logs.pjsip_level''' (type={{{NonNegativeInteger}}}, default={{{5}}})::
374 28 Luci Stanescu
  This setting controls the amount of log messages generated by the PJSIP core. It must be set to a non-negative integer.
375 28 Luci Stanescu
376 1 Adrian Georgescu
==== RTP ====
377 33 Luci Stanescu
378 48 Adrian Georgescu
 '''SIPSimpleSettings.rtp.port_range''' (type={{{PortRange}}}, default={{{PortRange(50000, 50500)}}})::
379 23 Adrian Georgescu
  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.
380 34 Luci Stanescu
381 48 Adrian Georgescu
 '''SIPSimpleSettings.rtp.audio_codec_list''' (type={{{AudioCodecLis}t}}, default={{{AudioCodecList(('G722', 'speex', 'PCMU', 'PCMA'))}}})::
382 33 Luci Stanescu
  This setting is used to specify the preferred audio codecs, which should be used for audio calls. It must contain only strings, which represent the supported codecs (speex, G722, PCMA, PCMU, iLBC and GSM), in the order in which they are preferred. This setting can be overridden per account.
383 23 Adrian Georgescu
384 48 Adrian Georgescu
'''SIPSimpleSettings.rtp.timeout''' (type={{{NonNegativeInteger}t}}, default={{{30))}}})::
385 48 Adrian Georgescu
  This setting is used to specify the time after which a notification is raised should no RTP be received from the other end. It can be used by an application to decide to terminate the session or print an alert.
386 48 Adrian Georgescu
387 43 Adrian Georgescu
==== SIP ====
388 43 Adrian Georgescu
389 48 Adrian Georgescu
 '''SIPSimpleSettings.sip.invite_timeout''' (type={{{NonNegativeInteger}}}, default={{{90}}})::
390 48 Adrian Georgescu
  This setting is used to terminate an outgoing session request in progress that does not receive a final answer before this internal in seconds is reached.
391 48 Adrian Georgescu
392 28 Luci Stanescu
 '''SIPSimpleSettings.sip.udp_port''' (type={{{Port}}}, default={{{0}}})::
393 8 Adrian Georgescu
  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.
394 28 Luci Stanescu
395 1 Adrian Georgescu
 '''SIPSimpleSettings.sip.tcp_port''' (type={{{Port}}}, default={{{0}}})::
396 8 Adrian Georgescu
  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.
397 1 Adrian Georgescu
398 28 Luci Stanescu
 '''SIPSimpleSettings.sip.tls_port''' (type={{{Port}}}, default={{{0}}})::
399 54 Adrian Georgescu
  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. The port must be different than the port used for TCP connections.
400 1 Adrian Georgescu
401 1 Adrian Georgescu
 '''SIPSimpleSettings.sip.transport_list''' (type={{{SIPTransportList}}}, default={{{SIPTransportList(('tls', 'tcp', 'udp'))}}})::
402 27 Luci Stanescu
  This setting's value is a tuple, which can only contain the strings 'tls', 'tcp' and 'udp'. It has a double purpose:
403 27 Luci Stanescu
   * Only the transports specified here are used to SIP requests associated with normal accounts.
404 29 Luci Stanescu
   * 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.
405 27 Luci Stanescu
406 33 Luci Stanescu
==== TLS ====
407 27 Luci Stanescu
408 1 Adrian Georgescu
 '''SIPSimpleSettings.tls.ca_list''' (type={{{Path}}}, default={{{None}}}, nillable={{{True}}})::
409 27 Luci Stanescu
  The settings points to a file which contains the CA certificates. In can be {{{None}}}, in which case no CAs are available. It is interpreted as an absolute path, with a leading ''~'' expanded to the home directory of the current user. In order to access the full path to the CA file, the normalized attribute on the setting can be used:
410 27 Luci Stanescu
  {{{
411 27 Luci Stanescu
  SIPSimpleSettings().tls.ca_list.normalized
412 31 Luci Stanescu
  }}}
413 27 Luci Stanescu
414 27 Luci Stanescu
 '''SIPSimpleSettings.tls.protocol''' (type={{{TLSProtocol}}}, default={{{'TLSv1'}}})::
415 53 Adrian Georgescu
  This setting sets the version of the TLS protocol which will be used. It is a string and must be one of {{{'TLSv1'}}}.
416 27 Luci Stanescu
417 48 Adrian Georgescu
 '''SIPSimpleSettings.tls.timeout''' (type={{{NonNegativeInteger}}}, default={{{3000}}})::
418 27 Luci Stanescu
  This is the timeout for negotiating TLS connections, in milliseconds. It must be an non-negative integer.
419 1 Adrian Georgescu
420 1 Adrian Georgescu
=== Account ===
421 1 Adrian Georgescu
422 1 Adrian Georgescu
{{{
423 27 Luci Stanescu
Account user@example.com:
424 33 Luci Stanescu
          +-- display_name = Example User
425 1 Adrian Georgescu
account --|-- enabled = True
426 1 Adrian Georgescu
          |-- auth
427 29 Luci Stanescu
          |-- dialog_event
428 29 Luci Stanescu
          |-- message_summary
429 48 Adrian Georgescu
          |-- msrp
430 45 Luci Stanescu
          |-- nat_traversal
431 29 Luci Stanescu
          |-- presence
432 29 Luci Stanescu
          |-- rtp
433 1 Adrian Georgescu
          |-- sip
434 1 Adrian Georgescu
          |-- tls
435 1 Adrian Georgescu
          +-- xcap
436 1 Adrian Georgescu
437 45 Luci Stanescu
       +-- password = xyz
438 45 Luci Stanescu
auth --|-- username = None
439 45 Luci Stanescu
       +
440 45 Luci Stanescu
441 29 Luci Stanescu
               +-- enabled = True
442 29 Luci Stanescu
dialog_event --|
443 29 Luci Stanescu
               +
444 29 Luci Stanescu
445 1 Adrian Georgescu
                  +-- enabled = True
446 29 Luci Stanescu
message_summary --|-- voicemail_uri = None
447 29 Luci Stanescu
                  +
448 29 Luci Stanescu
449 48 Adrian Georgescu
       +-- connection_model = relay
450 48 Adrian Georgescu
msrp --|-- transport = tls
451 48 Adrian Georgescu
       +
452 48 Adrian Georgescu
453 1 Adrian Georgescu
                +-- msrp_relay = None
454 1 Adrian Georgescu
nat_traversal --|-- stun_server_list = None
455 1 Adrian Georgescu
                |-- use_ice = False
456 1 Adrian Georgescu
                |-- use_msrp_relay_for_inbound = True
457 1 Adrian Georgescu
                +-- use_msrp_relay_for_outbound = False
458 1 Adrian Georgescu
459 30 Luci Stanescu
           +-- enabled = True
460 1 Adrian Georgescu
presence --|-- use_rls = True
461 1 Adrian Georgescu
           +
462 1 Adrian Georgescu
463 1 Adrian Georgescu
      +-- audio_codec_list = None
464 1 Adrian Georgescu
rtp --|-- inband_dtmf = False
465 30 Luci Stanescu
      |-- srtp_encryption = optional
466 1 Adrian Georgescu
      +-- use_srtp_without_tls = False
467 1 Adrian Georgescu
468 51 Adrian Georgescu
      +-- always_use_my_proxy = False
469 51 Adrian Georgescu
sip --|-- outbound_proxy = SIPProxyAddress('sip.example.com', port=5060, transport='udp')
470 51 Adrian Georgescu
      |-- publish_interval = 3600
471 30 Luci Stanescu
      |-- register = True
472 51 Adrian Georgescu
      |-- register_interval = 3600
473 51 Adrian Georgescu
      +-- subscribe_interval = 3600
474 1 Adrian Georgescu
475 1 Adrian Georgescu
      +-- certificate = tls/user@example.com.crt
476 1 Adrian Georgescu
tls --|-- verify_server = False
477 1 Adrian Georgescu
      +
478 1 Adrian Georgescu
479 1 Adrian Georgescu
       +-- enabled = True
480 52 Adrian Georgescu
xcap --|-- xcap_root = None
481 1 Adrian Georgescu
       +
482 1 Adrian Georgescu
}}}
483 1 Adrian Georgescu
484 1 Adrian Georgescu
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]. 
485 1 Adrian Georgescu
486 1 Adrian Georgescu
The settings that can be accessed on an Account are described below:
487 1 Adrian Georgescu
488 56 Adrian Georgescu
 '''Account.id''' (type={{{SIPAddress}}})::
489 1 Adrian Georgescu
  Its 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.
490 1 Adrian Georgescu
491 57 Adrian Georgescu
 '''Account.display_name''' (type={{{unicode}}}, default={{{None}}}, nillable={{{True}}})::
492 1 Adrian Georgescu
  The contents of this setting will be sent as part of the ''From'' header when sending SIP requests, the ''From'' CPIM header and other similar information.
493 1 Adrian Georgescu
494 30 Luci Stanescu
 '''Account.enabled''' (type={{{bool}}}, default={{{False}}})::
495 1 Adrian Georgescu
  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].
496 1 Adrian Georgescu
497 1 Adrian Georgescu
==== Auth ====
498 1 Adrian Georgescu
499 1 Adrian Georgescu
 '''Account.auth.username''' (type={{{str}}}, default={{{None}}}, nillable={{{True}}})::
500 1 Adrian Georgescu
  The username used for authentication if it is different from the one in the SIP ID of the account. If it is {{{None}}} or an empty string, the account SIP ID username will be used instead.
501 1 Adrian Georgescu
502 1 Adrian Georgescu
 '''Account.auth.password''' (type={{{str}}}, default={{{''}}})::
503 1 Adrian Georgescu
  The password, which will be used with this account for authentication.
504 1 Adrian Georgescu
505 1 Adrian Georgescu
506 45 Luci Stanescu
==== Dialog Event ====
507 45 Luci Stanescu
508 45 Luci Stanescu
 '''Account.dialog_event.enabled''' (type={{{bool}}}, default={{{True}}})::
509 45 Luci Stanescu
  If this setting is set to {{{True}}}, the Account will subscribe to the ''dialog'' event as specified by RFC4235.
510 45 Luci Stanescu
511 48 Adrian Georgescu
==== MSRP ====
512 48 Adrian Georgescu
513 48 Adrian Georgescu
 '''Account.msrp.transport''' (type={{{MSRPTransport}}}, default={{{'tls'}}})::
514 48 Adrian Georgescu
  MSRP can use either TLS or TCP and this setting controls which one should be used for normal accounts.
515 48 Adrian Georgescu
516 48 Adrian Georgescu
 '''Account.msrp.connection_model''' (type={{{MSRPConnectionModel}}}, default={{{'relay'}}})::
517 48 Adrian Georgescu
  Whether {{{relay}}} or {{{acm}}} connection models shall be used for NAT traversal purposes.
518 48 Adrian Georgescu
519 48 Adrian Georgescu
520 33 Luci Stanescu
==== Message Summary ====
521 1 Adrian Georgescu
522 1 Adrian Georgescu
 '''Account.message_summary.enabled''' (type={{{bool}}}, default={{{True}}})::
523 1 Adrian Georgescu
  If this setting is set to {{{True}}}, the Account will subscribe to the ''message-summary'' event, as specified by RFC3842.
524 1 Adrian Georgescu
525 1 Adrian Georgescu
 '''Account.message_summary.voicemail_uri''' (type={{{str}}}, default={{{None}}}, nillable={{{True}}})::
526 47 Adrian Georgescu
  This is the SIP URI where the Subscribe is sent and where the user can call to listen to the voicemail messages.
527 1 Adrian Georgescu
528 1 Adrian Georgescu
==== NAT Traversal ====
529 33 Luci Stanescu
530 1 Adrian Georgescu
 '''Account.nat_traversal.use_ice''' (type={{{bool}}}, default={{{False}}})::
531 1 Adrian Georgescu
  If this setting is set to {{{True}}}, ICE will be used for finding media candidates for communication over NAT-ed networks.
532 1 Adrian Georgescu
533 1 Adrian Georgescu
 '''Account.nat_traversal.stun_server_list''' (type={{{StunServerAddressList}}}, default={{{None}}}, nillable={{{True}}})::
534 1 Adrian Georgescu
  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).
535 1 Adrian Georgescu
536 1 Adrian Georgescu
 '''Account.nat_traversal.msrp_relay''' (type={{{MSRPRelayAddress}}}, default={{{None}}}, nillable={{{True}}})::
537 30 Luci Stanescu
  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).
538 1 Adrian Georgescu
539 1 Adrian Georgescu
 '''Account.nat_traversal.use_msrp_relay_for_inbound''' (type={{{bool}}}, default={{{True}}})::
540 1 Adrian Georgescu
  If this setting is set to {{{True}}}, the MSRP relay will be used for all incoming MSRP connections.
541 1 Adrian Georgescu
542 1 Adrian Georgescu
 '''Account.nat_traversal.use_msrp_relay_for_outbound''' (type={{{bool}}}, default={{{False}}})::
543 1 Adrian Georgescu
  If this setting is set to {{{True}}}, the MSRP relay will be used for all outgoing MSRP connections.
544 30 Luci Stanescu
545 30 Luci Stanescu
==== Presence ====
546 33 Luci Stanescu
547 1 Adrian Georgescu
 '''Account.presence.enabled''' (type={{{bool}}}, default={{{True}}})::
548 30 Luci Stanescu
  If this setting is set to {{{True}}}, the Account will publish its presence state and subscribe to presence and presence.winfo Event packages.
549 1 Adrian Georgescu
550 50 Adrian Georgescu
 '''Account.presence.use_rls''' (type={{{bool}}}, default={{{False}}})::
551 30 Luci Stanescu
  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.
552 30 Luci Stanescu
553 30 Luci Stanescu
==== RTP ====
554 33 Luci Stanescu
555 30 Luci Stanescu
 '''Account.rtp.audio_codecs''' (type={{{AudioCodecList}}}, default={{{None}}}, nillable={{{True}}})::
556 1 Adrian Georgescu
  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.
557 1 Adrian Georgescu
558 1 Adrian Georgescu
 '''Account.audio.srtp_encryption''' (type={{{SRTPEncryption}}}, default={{{'optional'}}})::
559 1 Adrian Georgescu
  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'}}}.
560 1 Adrian Georgescu
561 1 Adrian Georgescu
 '''Account.audio.use_srtp_without_tls''' (type={{{bool}}}, default={{{False}}})::
562 1 Adrian Georgescu
  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.
563 1 Adrian Georgescu
564 1 Adrian Georgescu
565 1 Adrian Georgescu
==== SIP ====
566 51 Adrian Georgescu
567 51 Adrian Georgescu
 '''Account.sip.always_use_my_proxy''' (type={{{bool}}}, default={{{False}}})::
568 51 Adrian Georgescu
  If this setting is set to {{{True}}} and the outbound proxy is not set, the signalling for outbound requests going to foreign domains will be sent to the account proxy instead of sending it to the foreign proxy.
569 1 Adrian Georgescu
570 30 Luci Stanescu
 '''Account.sip.outbound_proxy''' (type={{{SIPProxyAddress}}}, default={{{None}}}, nillable={{{True}}})::
571 1 Adrian Georgescu
  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.
572 1 Adrian Georgescu
573 1 Adrian Georgescu
 '''Account.sip.register''' (type={{{bool}}}, default={{{True}}})::
574 1 Adrian Georgescu
  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].
575 1 Adrian Georgescu
576 48 Adrian Georgescu
 '''Account.sip.publish_interval''' (type={{{NonNegativeInteger}}}, default={{{3600}}})::
577 31 Luci Stanescu
  This setting controls the number of seconds used for the ''Expire'' header when publishing events. It must be a non-negative integer.
578 31 Luci Stanescu
579 48 Adrian Georgescu
 '''Account.sip.subscribe_interval''' (type={{{NonNegativeInteger}}}, default={{{3600}}})::
580 31 Luci Stanescu
  This setting controls the number of seconds used for the ''Expire'' header when subscribing to events. It must be a non-negative integer.
581 31 Luci Stanescu
582 31 Luci Stanescu
 '''Account.registration.interval''' (type={{{NonNegativeInteger}}}, default={{{600}}})::
583 31 Luci Stanescu
  This setting controls the number of seconds used for the ''Expire'' header when registering. It must be a non-negative integer.
584 31 Luci Stanescu
585 33 Luci Stanescu
==== TLS ====
586 31 Luci Stanescu
587 1 Adrian Georgescu
 '''Account.tls.certificate''' (type={{{Path}}}, default={{{None}}}, nillable={{{True}}})::
588 31 Luci Stanescu
  The path to the file that contains the certificate and its private key used to authenticate on TLS connections. It is interpreted as an absolute path, with a leading ''~'' expanded to the home directory of the current user. In order to access the full path to the TLS certificate, the normalized attribute on the setting can be used:
589 31 Luci Stanescu
  {{{
590 31 Luci Stanescu
  account.tls.certificate.normalized
591 31 Luci Stanescu
  }}}
592 31 Luci Stanescu
593 31 Luci Stanescu
 '''Account.tls.verify_server''' (type={{{bool}}}, default={{{False}}})::
594 31 Luci Stanescu
  If this setting is set to {{{True}}}, the middleware will verify the server's certificate when connecting via TLS.
595 31 Luci Stanescu
596 33 Luci Stanescu
==== XCAP  ====
597 31 Luci Stanescu
598 31 Luci Stanescu
 '''Account.xcap.enabled''' (type={{{bool}}}, default={{{True}}})::
599 31 Luci Stanescu
  If this setting is set to {{{True}}}, The use of XCAP root set below will be activated.
600 31 Luci Stanescu
601 31 Luci Stanescu
 '''Account.xcap.xcap_root''' (type={{{XCAPRoot}}}, default={{{None}}}, nillable={{{True}}})::
602 31 Luci Stanescu
  The XCAP root is required for accessing documents via the XCAP protocol. It must be a URL with either the ''http'' or ''https'' schemes.
603 31 Luci Stanescu
604 1 Adrian Georgescu
605 1 Adrian Georgescu
606 33 Luci Stanescu
=== BonjourAccount ===
607 1 Adrian Georgescu
608 30 Luci Stanescu
{{{
609 1 Adrian Georgescu
Account bonjour@local:
610 1 Adrian Georgescu
          +-- display_name = Bonjour User
611 1 Adrian Georgescu
account --|-- enabled = False
612 34 Luci Stanescu
          |-- msrp
613 1 Adrian Georgescu
          |-- rtp
614 34 Luci Stanescu
          |-- sip
615 1 Adrian Georgescu
          +-- tls
616 34 Luci Stanescu
617 34 Luci Stanescu
       +-- transport = tcp
618 34 Luci Stanescu
msrp --|
619 34 Luci Stanescu
       +
620 1 Adrian Georgescu
621 1 Adrian Georgescu
      +-- audio_codec_list = None
622 1 Adrian Georgescu
rtp --|-- inband_dtmf = False
623 1 Adrian Georgescu
      |-- srtp_encryption = optional
624 30 Luci Stanescu
      +-- use_srtp_without_tls = False
625 1 Adrian Georgescu
626 45 Luci Stanescu
      +-- transport_list = SIPTransportList(['udp'])
627 34 Luci Stanescu
sip --|
628 34 Luci Stanescu
      +
629 34 Luci Stanescu
630 30 Luci Stanescu
      +-- certificate = tls/bonjour@local.crt
631 1 Adrian Georgescu
tls --|-- verify_server = False
632 30 Luci Stanescu
      +
633 1 Adrian Georgescu
}}}
634 30 Luci Stanescu
635 1 Adrian Georgescu
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. 
636 30 Luci Stanescu
637 30 Luci Stanescu
The settings of the BonjourAccount are described below:
638 30 Luci Stanescu
 
639 30 Luci Stanescu
 '''BonjourAccount.id''' (type={{{SIPAddress}}})::
640 30 Luci Stanescu
  This is not a setting, as it is the static string 'bonjour@local' which represents the id of the BonjourAccount.
641 30 Luci Stanescu
642 30 Luci Stanescu
 '''BonjourAccount.enabled''' (type={{{bool}}}, default={{{True}}})::
643 1 Adrian Georgescu
  If this setting is set to {{{True}}}, the account will be used. More information about this is in [wiki:SipMiddlewareApi#BonjourAccount BonjourAccount].
644 30 Luci Stanescu
645 57 Adrian Georgescu
 '''BonjourAccount.display_name''' (type={{{unicode}}}, default={{{None}}}, nillable={{{True}}})::
646 1 Adrian Georgescu
  The contents of this setting will be sent as part of the ''From'' header when sending SIP requests.
647 1 Adrian Georgescu
648 34 Luci Stanescu
==== MSRP ====
649 34 Luci Stanescu
650 1 Adrian Georgescu
 '''SIPSimpleSettings.msrp.transport''' (type={{{MSRPTransport}}}, default={{{'tcp'}}})::
651 1 Adrian Georgescu
  MSRP can use either TLS or TCP and this setting controls which one should be used for the bonjour account.
652 1 Adrian Georgescu
653 1 Adrian Georgescu
==== RTP ====
654 34 Luci Stanescu
655 34 Luci Stanescu
 '''BonjourAccount.rtp.audio_codec_list''' (type={{{AudioCodecList}}}, default={{{('speex', 'g722', 'g711', 'ilbc', 'gsm')}}})::
656 34 Luci Stanescu
  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.
657 33 Luci Stanescu
658 30 Luci Stanescu
 '''BonjourAccount.rtp.srtp_encryption''' (type={{{SRTPEncryption}}}, default={{{'optional'}}})::
659 30 Luci Stanescu
  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'}}}.
660 32 Luci Stanescu
661 30 Luci Stanescu
 '''BonjourAccount.rtp.use_srtp_without_tls''' (type={{{bool}}}, default={{{False}}})::
662 30 Luci Stanescu
  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.
663 30 Luci Stanescu
664 34 Luci Stanescu
==== TLS ====
665 34 Luci Stanescu
666 34 Luci Stanescu
 '''BonjourAccount.tls.certificate''' (type={{{Path}}}, default={{{None}}}, nillable={{{True}}})::
667 30 Luci Stanescu
  The path to the file that contains the certificate and its private key used to authenticate on TLS connections. It is interpreted as an absolute path, with a leading ''~'' expanded to the home directory of the current user. In order to access the full path to the certificate file, the normalized attribute on the setting can be used:
668 33 Luci Stanescu
  {{{
669 30 Luci Stanescu
  BonjourAccount().tls.ca_list.normalized
670 30 Luci Stanescu
  }}}
671 30 Luci Stanescu
672 30 Luci Stanescu
 '''BonjourAccount.tls.verify_server''' (type={{{bool}}}, default={{{False}}})::
673 30 Luci Stanescu
  If this setting is set to {{{True}}}, the middleware will verify the server's certificate when connecting via TLS.
674 30 Luci Stanescu
675 30 Luci Stanescu
== SIPClients Settings ==
676 30 Luci Stanescu
677 30 Luci Stanescu
The SIPClients scripts use the Configuration API to extend the settings in the middleware with some application-specific settings. The following sections list these additional settings in order to provide an example for the kind of settings which, being application specific, do not find their place in the middleware and should be added by the application.
678 29 Luci Stanescu
679 35 Luci Stanescu
=== General ===
680 30 Luci Stanescu
681 30 Luci Stanescu
 '''SIPSimpleSettings.user_data_directory''' (type={{{AbsolutePath}}}, default={{{'~/.sipclient}}})::
682 29 Luci Stanescu
  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.
683 48 Adrian Georgescu
684 48 Adrian Georgescu
 '''SIPSimpleSettings.resources_directory''' (type={{{AbsolutePath}}}, default={{{None}}})::
685 48 Adrian Georgescu
  This is the directory, which will be used by default for storing the sound files played for various notifications.
686 48 Adrian Georgescu
687 29 Luci Stanescu
688 33 Luci Stanescu
==== Audio ====
689 29 Luci Stanescu
690 29 Luci Stanescu
 '''SIPSimpleSettings.audio.directory''' (type={{{DataPath}}}, default={{{DataPath('history')}}})::
691 29 Luci Stanescu
  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:
692 29 Luci Stanescu
  {{{
693 29 Luci Stanescu
  SIPSimpleSettings().audio.directory.value
694 29 Luci Stanescu
  }}}
695 29 Luci Stanescu
696 33 Luci Stanescu
==== File Transfer ====
697 29 Luci Stanescu
698 29 Luci Stanescu
 '''SIPSimpleSettings.file_transfer.directory''' (type={{{DataPath}}}, default={{{DataPath('file_transfers')}}})::
699 29 Luci Stanescu
  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:
700 29 Luci Stanescu
  {{{
701 29 Luci Stanescu
  SIPSimpleSettings().file_transfer.directory.value
702 29 Luci Stanescu
  }}}
703 29 Luci Stanescu
704 33 Luci Stanescu
==== Logs ====
705 29 Luci Stanescu
706 29 Luci Stanescu
 '''SIPSimpleSettings.logs.directory''' (type={{{DataPath}}}, default={{{DataPath('logs')}}})::
707 29 Luci Stanescu
  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:
708 29 Luci Stanescu
  {{{
709 29 Luci Stanescu
  SIPSimpleSettings().logs.directory.value
710 29 Luci Stanescu
  }}}
711 29 Luci Stanescu
712 29 Luci Stanescu
 '''SIPSimpleSettings.logs.trace_sip''' (type={{{bool}}}, default={{{False}}})::
713 29 Luci Stanescu
  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}}}.
714 29 Luci Stanescu
715 29 Luci Stanescu
 '''SIPSimpleSettings.logs.trace_pjsip''' (type={{{bool}}}, default={{{False}}})::
716 29 Luci Stanescu
  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}}}.
717 29 Luci Stanescu
718 29 Luci Stanescu
 '''SIPSimpleSettings.logs.trace_msrp''' (type={{{bool}}}, default={{{False}}})::
719 29 Luci Stanescu
  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}}}.
720 29 Luci Stanescu
721 29 Luci Stanescu
 '''SIPSimpleSettings.logs.trace_xcap''' (type={{{bool}}}, default={{{False}}})::
722 29 Luci Stanescu
  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}}}.
723 29 Luci Stanescu
724 33 Luci Stanescu
==== Sounds ====
725 29 Luci Stanescu
726 29 Luci Stanescu
 '''SIPSimpleSettings.sounds.audio_inbound''' (type={{{AbsolutePath}}}, default={{{None}}}, nillable={{{True}}})::
727 29 Luci Stanescu
  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.
728 29 Luci Stanescu
729 29 Luci Stanescu
 '''SIPSimpleSettings.sounds.audio_outbound''' (type={{{AbsolutePath}}}, default={{{None}}}, nillable={{{True}}})::
730 29 Luci Stanescu
  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.
731 29 Luci Stanescu
732 29 Luci Stanescu
 '''SIPSimpleSettings.sounds.file_sent''' (type={{{AbsolutePath}}}, default={{{None}}}, nillable={{{True}}})::
733 29 Luci Stanescu
  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.
734 29 Luci Stanescu
735 29 Luci Stanescu
 '''SIPSimpleSettings.sounds.file_received''' (type={{{AbsolutePath}}}, default={{{None}}}, nillable={{{True}}})::
736 29 Luci Stanescu
  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.
737 29 Luci Stanescu
738 29 Luci Stanescu
 '''SIPSimpleSettings.sounds.message_sent''' (type={{{AbsolutePath}}}, default={{{None}}}, nillable={{{True}}})::
739 29 Luci Stanescu
  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.
740 29 Luci Stanescu
741 29 Luci Stanescu
 '''SIPSimpleSettings.sounds.message_received''' (type={{{AbsolutePath}}}, default={{{None}}}, nillable={{{True}}})::
742 29 Luci Stanescu
  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.
743 29 Luci Stanescu
744 33 Luci Stanescu
=== Account ===
745 29 Luci Stanescu
746 33 Luci Stanescu
==== Sounds ====
747 29 Luci Stanescu
748 29 Luci Stanescu
 '''Account.sounds.audio_inbound''' (type={{{AbsolutePath}}}, default={{{None}}}, nillable={{{True}}})::
749 29 Luci Stanescu
  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.
750 29 Luci Stanescu
751 33 Luci Stanescu
=== BonjourAccount ===
752 29 Luci Stanescu
753 33 Luci Stanescu
==== Sounds ====
754 29 Luci Stanescu
755 29 Luci Stanescu
 '''BonjourAccount.sounds.audio_inbound''' (type={{{AbsolutePath}}}, default={{{None}}}, nillable={{{True}}})::
756 1 Adrian Georgescu
  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.