Project

General

Profile

SipConfigurationAPI » History » Version 31

Luci Stanescu, 03/23/2010 05:15 PM

1 1 Adrian Georgescu
= Configuration API =
2
3
[[TOC(WikiStart, Sip*, depth=2)]]
4
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 28 Luci Stanescu
The settings can be managed by API calls. The configuration API has appropriate defaults so that the middleware can function properly with a minimum amount of changes.
8 1 Adrian Georgescu
9 27 Luci Stanescu
== Middleware Settings Index ==
10 1 Adrian Georgescu
11 2 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].
12 1 Adrian Georgescu
13 27 Luci Stanescu
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}}}.
14 1 Adrian Georgescu
15 20 Adrian Georgescu
== General ==
16 5 Adrian Georgescu
17 7 Adrian Georgescu
{{{
18 23 Adrian Georgescu
SIP SIMPLE settings:
19
             +-- default_account = user@example.com
20 27 Luci Stanescu
SIP SIMPLE --|-- user_agent = sipsimple
21 4 Adrian Georgescu
             |-- audio
22 1 Adrian Georgescu
             |-- chat
23 4 Adrian Georgescu
             |-- desktop_sharing
24
             |-- file_transfer
25 1 Adrian Georgescu
             |-- logs
26 4 Adrian Georgescu
             |-- msrp
27
             |-- rtp
28 1 Adrian Georgescu
             |-- sip
29
             +-- tls
30 22 Adrian Georgescu
31
        +-- alert_device = system_default
32 27 Luci Stanescu
audio --|-- input_device = system_default
33 17 Adrian Georgescu
        |-- output_device = system_default
34 22 Adrian Georgescu
        |-- sample_rate = 44100
35 4 Adrian Georgescu
        |-- silent = False
36 22 Adrian Georgescu
        +-- tail_length = 200
37 1 Adrian Georgescu
38
       +
39 23 Adrian Georgescu
chat --|
40 17 Adrian Georgescu
       +
41 1 Adrian Georgescu
42
                  +
43
desktop_sharing --|
44
                  +
45
46 27 Luci Stanescu
                +
47 17 Adrian Georgescu
file_transfer --|
48 1 Adrian Georgescu
                +
49
50 27 Luci Stanescu
       +-- pjsip_level = 5
51
logs --|
52
       +
53 1 Adrian Georgescu
54 23 Adrian Georgescu
       +-- transport = tls
55
msrp --|
56 22 Adrian Georgescu
       +
57 17 Adrian Georgescu
58
      +-- audio_codec_list = AudioCodecList(['speex', 'G722', 'PCMU', 'PCMA', 'iLBC', 'GSM'])
59 22 Adrian Georgescu
rtp --|-- port_range = PortRange(start=50000, end=50400)
60 23 Adrian Georgescu
      +-- timeout = 30
61
62
      +-- tcp_port = 0
63
sip --|-- tls_port = 0
64
      |-- transport_list = SIPTransportList(['tls', 'tcp', 'udp'])
65
      +-- udp_port = 0
66 18 Adrian Georgescu
67 22 Adrian Georgescu
      +-- ca_list = None
68 18 Adrian Georgescu
tls --|-- protocol = TLSv1
69 17 Adrian Georgescu
      +-- timeout = 1000
70 22 Adrian Georgescu
71 4 Adrian Georgescu
}}}
72 1 Adrian Georgescu
73
The {{{sipsimple.configuration.settings.SIPSimpleSettings}}} class is a singleton can be instantiated and used anywhere after the [wiki:SipConfigurationAPI#ConfigurationManager ConfigurationManager] has been started. 
74
75
The settings are explained below:
76 2 Adrian Georgescu
77 1 Adrian Georgescu
 '''SIPSimpleSettings.default_account''' (type={{{str}}}, default={{{'bonjour@local'}}}, nillable={{{True}}})::
78
  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.
79
80
 '''SIPSimpleSettings.user_agent''' (type={{{str}}}, default={{{'sipsimple VERSION'}}})::
81
  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.
82
83
=== Audio ===
84
85 28 Luci Stanescu
 '''SIPSimpleSettings.audio.input_device''' (type={{{AudioInputDevice}}}, default={{{'system_default'}}}, nillable={{{True}}})::
86
  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.
87 1 Adrian Georgescu
88 28 Luci Stanescu
 '''SIPSimpleSettings.audio.output_device''' (type={{{AudioOutputDevice}}}, default={{{'system_default'}}}, nillable={{{True}}})::
89
  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.
90 1 Adrian Georgescu
91 28 Luci Stanescu
 '''SIPSimpleSettings.audio.alert_device''' (type={{{AudioOutputDevice}}}, default={{{'system_default'}}}, nillable={{{True}}})::
92
  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.
93 24 Adrian Georgescu
94 1 Adrian Georgescu
 '''SIPSimpleSettings.audio.tail_length''' (type={{{NonNegativeInteger}}}, default={{{200}}})::
95
  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.
96
97 28 Luci Stanescu
 '''SIPSimpleSettings.audio.sample_rate''' (type={{{SampleRate}}}, default={{{16000}}})::
98
  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.
99 1 Adrian Georgescu
 
100
 '''SIPSimpleSettings.audio.silent''' (type={{{bool}}}, default={{{False}}})::
101 28 Luci Stanescu
  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).
102 17 Adrian Georgescu
103 1 Adrian Georgescu
=== Chat ===
104
105 23 Adrian Georgescu
Empty section for future use.
106 1 Adrian Georgescu
107 4 Adrian Georgescu
=== Desktop Sharing ===
108 24 Adrian Georgescu
109 1 Adrian Georgescu
Empty section for future use.
110
111 24 Adrian Georgescu
=== File Transfer ===
112 4 Adrian Georgescu
113 27 Luci Stanescu
Empty section for future use.
114 24 Adrian Georgescu
115 1 Adrian Georgescu
=== Logs ===
116
117
 '''SIPSimpleSettings.logs.pjsip_level''' (type={{{NonNegativeInteger}}}, default={{{5}}})::
118
  This setting controls the amount of log messages generated by the PJSIP core. It must be set to a non-negative integer.
119
120 23 Adrian Georgescu
=== MSRP ===
121 4 Adrian Georgescu
122 23 Adrian Georgescu
 '''SIPSimpleSettings.msrp.transport''' (type={{{MSRPTransport}}}, default={{{'tls'}}})::
123
  MSRP can use either TLS or TCP and this setting controls which one should be used.
124 1 Adrian Georgescu
125 23 Adrian Georgescu
=== RTP ===
126 1 Adrian Georgescu
127
 '''SIPSimpleSettings.rtp.port_range''' (type={{{PortRange}}}, default={{{PortRange(50000, 50400)}}})::
128 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.
129
130 28 Luci Stanescu
 '''SIPSimpleSettings.rtp.audio_codec_list''' (type={{{AudioCodecLis}t}}, default={{{AudioCodecList(('speex', 'G722', 'PCMU', 'PCMA', 'iLBC', 'GSM'))}}})::
131
  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, g711, ilbc and gsm), in the order in which they are preferred. This setting can be overridden per account.
132 1 Adrian Georgescu
133
=== SIP ===
134
135 23 Adrian Georgescu
 '''SIPSimpleSettings.sip.udp_port''' (type={{{Port}}}, default={{{0}}})::
136 1 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.
137 23 Adrian Georgescu
138
 '''SIPSimpleSettings.sip.tcp_port''' (type={{{Port}}}, default={{{0}}})::
139
  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.
140
141
 '''SIPSimpleSettings.sip.tls_port''' (type={{{Port}}}, default={{{0}}})::
142
  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.
143
144 28 Luci Stanescu
 '''SIPSimpleSettings.sip.transport_list''' (type={{{SIPTransportList}}}, default={{{SIPTransportList(('tls', 'tcp', 'udp'))}}})::
145 23 Adrian Georgescu
  This setting's value is a tuple, which can only contain the strings 'tls', 'tcp' and 'udp'. It has a double purpose:
146
   * Only the transports specified here are used to SIP requests associated with normal accounts.
147
   * 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.
148
149
=== TLS ===
150
151 28 Luci Stanescu
 '''SIPSimpleSettings.tls.ca_list''' (type={{{Path}}}, default={{{None}}}, nillable={{{True}}})::
152
  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:
153 23 Adrian Georgescu
  {{{
154 28 Luci Stanescu
  SIPSimpleSettings().tls.ca_list.normalized
155 23 Adrian Georgescu
  }}}
156
157 24 Adrian Georgescu
 '''SIPSimpleSettings.tls.protocol''' (type={{{TLSProtocol}}}, default={{{'TLSv1'}}})::
158 23 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'}}}, {{{'SSLv2'}}}, {{{'SSL3'}}}, {{{'SSL23'}}}.
159
160 24 Adrian Georgescu
 '''SIPSimpleSettings.tls.timeout''' (type={{{NonNegativeInteger}}}, default={{{1000}}})::
161 1 Adrian Georgescu
  This is the timeout for negotiating TLS connections, in milliseconds. It must be an non-negative integer.
162
163
== Account ==
164
165 22 Adrian Georgescu
{{{
166 24 Adrian Georgescu
Account user@example.com:
167 22 Adrian Georgescu
          +-- display_name = Example User
168 8 Adrian Georgescu
account --|-- enabled = True
169 1 Adrian Georgescu
          |-- password = xyz
170
          |-- dialog_event
171
          |-- message_summary
172
          |-- nat_traversal
173 24 Adrian Georgescu
          |-- presence
174 1 Adrian Georgescu
          |-- pstn
175
          |-- rtp
176 22 Adrian Georgescu
          |-- sip
177
          |-- tls
178 1 Adrian Georgescu
          +-- xcap
179 8 Adrian Georgescu
180 24 Adrian Georgescu
               +-- enabled = True
181
dialog_event --|
182
               +
183 22 Adrian Georgescu
184
                  +-- enabled = True
185 8 Adrian Georgescu
message_summary --|-- voicemail_uri = None
186
                  +
187
188 24 Adrian Georgescu
                +-- msrp_relay = None
189
nat_traversal --|-- stun_server_list = None
190
                |-- use_ice = False
191 1 Adrian Georgescu
                |-- use_msrp_relay_for_inbound = True
192
                +-- use_msrp_relay_for_outbound = False
193
194 24 Adrian Georgescu
           +-- enabled = True
195
presence --|-- use_rls = True
196
           +
197 8 Adrian Georgescu
198 24 Adrian Georgescu
       +
199
pstn --|
200
       +
201
202 22 Adrian Georgescu
      +-- audio_codec_list = None
203 1 Adrian Georgescu
rtp --|-- inband_dtmf = False
204 24 Adrian Georgescu
      |-- srtp_encryption = optional
205
      +-- use_srtp_without_tls = False
206
207 1 Adrian Georgescu
      +-- outbound_proxy = SIPProxyAddress('sip.example.com', port=5060, transport='udp')
208
sip --|-- publish_interval = 600
209
      |-- register = True
210
      |-- register_interval = 600
211 24 Adrian Georgescu
      +-- subscribe_interval = 600
212 1 Adrian Georgescu
213
214 24 Adrian Georgescu
      +-- certificate = tls/user@example.com.crt
215 1 Adrian Georgescu
tls --|-- verify_server = False
216
      +
217
218 8 Adrian Georgescu
       +-- enabled = True
219 24 Adrian Georgescu
xcap --|-- use_xcap_diff = True
220 1 Adrian Georgescu
       +-- xcap_root = https://xcap.example.com/xcap-root/
221
}}}
222
223
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]. 
224
225
The settings that can be accessed on an Account are described below:
226
227
 '''Account.id''' (type={{{SIPAddress}}})::
228 28 Luci Stanescu
  This is not a setting, as it cannot be modified. 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.
229 1 Adrian Georgescu
230 24 Adrian Georgescu
 '''Account.display_name''' (type={{{str}}}, default={{{None}}}, nillable={{{True}}})::
231 28 Luci Stanescu
  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.
232 24 Adrian Georgescu
233 1 Adrian Georgescu
 '''Account.enabled''' (type={{{bool}}}, default={{{False}}})::
234
  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].
235
236
 '''Account.password''' (type={{{str}}}, default={{{''}}})::
237
  The password, which will be used with this account for authentication.
238
239
240 24 Adrian Georgescu
=== Dialog Event ===
241 1 Adrian Georgescu
242 24 Adrian Georgescu
 '''Account.dialog_event.enabled''' (type={{{bool}}}, default={{{True}}})::
243
  If this setting is set to {{{True}}}, the Account will subscribe to the ''dialog'' event as specified by RFC4235.
244 1 Adrian Georgescu
245 24 Adrian Georgescu
=== Message Summary ===
246 1 Adrian Georgescu
247 28 Luci Stanescu
 '''Account.message_summary.enabled''' (type={{{bool}}}, default={{{True}}})::
248 1 Adrian Georgescu
  If this setting is set to {{{True}}}, the Account will subscribe to the ''message-summary'' event, as specified by RFC3842.
249 24 Adrian Georgescu
250 1 Adrian Georgescu
 '''Account.message_summary.voicemail_uri''' (type={{{str}}}, default={{{None}}}, nillable={{{True}}})::
251 8 Adrian Georgescu
  This is the SIP URI which can be called to listen to the voicemail messages.
252 24 Adrian Georgescu
253 1 Adrian Georgescu
=== NAT Traversal ===
254
255 22 Adrian Georgescu
 '''Account.nat_traversal.use_ice''' (type={{{bool}}}, default={{{False}}})::
256 24 Adrian Georgescu
  If this setting is set to {{{True}}}, ICE will be used for finding media candidates for communication over NAT-ed networks.
257 1 Adrian Georgescu
258 28 Luci Stanescu
 '''Account.nat_traversal.stun_server_list''' (type={{{StunServerAddressList}}}, default={{{None}}}, nillable={{{True}}})::
259 25 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).
260 22 Adrian Georgescu
261
 '''Account.nat_traversal.msrp_relay''' (type={{{MSRPRelayAddress}}}, default={{{None}}}, nillable={{{True}}})::
262 25 Adrian Georgescu
  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).
263 1 Adrian Georgescu
264 22 Adrian Georgescu
 '''Account.nat_traversal.use_msrp_relay_for_inbound''' (type={{{bool}}}, default={{{True}}})::
265
  If this setting is set to {{{True}}}, the MSRP relay will be used for all incoming MSRP connections.
266
267
 '''Account.nat_traversal.use_msrp_relay_for_outbound''' (type={{{bool}}}, default={{{False}}})::
268
  If this setting is set to {{{True}}}, the MSRP relay will be used for all outgoing MSRP connections.
269
270 24 Adrian Georgescu
=== Presence  ===
271 22 Adrian Georgescu
272 24 Adrian Georgescu
 '''Account.presence.enabled''' (type={{{bool}}}, default={{{True}}})::
273 28 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.
274 1 Adrian Georgescu
275 28 Luci Stanescu
 '''Account.presence.use_rls''' (type={{{bool}}}, default={{{True}}})::
276 24 Adrian Georgescu
  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.
277 1 Adrian Georgescu
278 21 Adrian Georgescu
=== RTP ===
279 1 Adrian Georgescu
280 28 Luci Stanescu
 '''Account.rtp.audio_codecs''' (type={{{AudioCodecList}}}, default={{{None}}}, nillable={{{True}}})::
281 8 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.
282 1 Adrian Georgescu
283 8 Adrian Georgescu
 '''Account.audio.srtp_encryption''' (type={{{SRTPEncryption}}}, default={{{'optional'}}})::
284
  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'}}}.
285
286 1 Adrian Georgescu
 '''Account.audio.use_srtp_without_tls''' (type={{{bool}}}, default={{{False}}})::
287 8 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.
288
289 24 Adrian Georgescu
=== SIP ===
290 8 Adrian Georgescu
291 28 Luci Stanescu
 '''Account.sip.outbound_proxy''' (type={{{SIPProxyAddress}}}, default={{{None}}}, nillable={{{True}}})::
292 24 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.
293
294
 '''Account.sip.register''' (type={{{bool}}}, default={{{True}}})::
295
  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].
296
297
 '''Account.sip.publish_interval''' (type={{{NonNegativeInteger}}}, default={{{600}}})::
298 1 Adrian Georgescu
  This setting controls the number of seconds used for the ''Expire'' header when publishing events. It must be a non-negative integer.
299
300
 '''Account.sip.subscribe_interval''' (type={{{NonNegativeInteger}}}, default={{{600}}})::
301
  This setting controls the number of seconds used for the ''Expire'' header when subscribing to events. It must be a non-negative integer.
302
303
 '''Account.registration.interval''' (type={{{NonNegativeInteger}}}, default={{{600}}})::
304
  This setting controls the number of seconds used for the ''Expire'' header when registering. It must be a non-negative integer.
305
306
=== TLS ===
307
308 28 Luci Stanescu
 '''Account.tls.certificate''' (type={{{Path}}}, default={{{None}}}, nillable={{{True}}})::
309
  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:
310 1 Adrian Georgescu
  {{{
311 28 Luci Stanescu
  account.tls.certificate.normalized
312 1 Adrian Georgescu
  }}}
313
314
 '''Account.tls.verify_server''' (type={{{bool}}}, default={{{False}}})::
315
  If this setting is set to {{{True}}}, the middleware will verify the server's certificate when connecting via TLS.
316
317
=== XCAP  ===
318
319
 '''Account.xcap.enabled''' (type={{{bool}}}, default={{{True}}})::
320
  If this setting is set to {{{True}}}, The use of XCAP root set below will be activated.
321
322
 '''Account.xcap.xcap_root''' (type={{{XCAPRoot}}}, default={{{None}}}, nillable={{{True}}})::
323
  The XCAP root is required for accessing documents via the XCAP protocol. It must be a URL with either the ''http'' or ''https'' schemes.
324
325
 '''Account.xcap.use_xcap_diff''' (type={{{bool}}}, default={{{True}}})::
326
  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.
327
328
329
== BonjourAccount ==
330
331
{{{
332
Account bonjour@local:
333
          +-- display_name = Bonjour User
334
account --|-- enabled = False
335
          |-- rtp
336
          +-- tls
337
338
      +-- audio_codec_list = None
339
rtp --|-- inband_dtmf = False
340
      |-- srtp_encryption = optional
341
      +-- use_srtp_without_tls = False
342
343
      +-- certificate = tls/bonjour@local.crt
344
tls --|-- verify_server = False
345
      +
346
}}}
347
348
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. 
349
350
The settings of the BonjourAccount are described below:
351
 
352
 '''BonjourAccount.id''' (type={{{SIPAddress}}})::
353
  This is not a setting, as it is the static string 'bonjour@local' which represents the id of the BonjourAccount.
354
355
 '''BonjourAccount.enabled''' (type={{{bool}}}, default={{{True}}})::
356
  If this setting is set to {{{True}}}, the account will be used. More information about this is in [wiki:SipMiddlewareApi#BonjourAccount BonjourAccount].
357
358
 '''BonjourAccount.display_name''' (type={{{str}}}, default={{{None}}}, nillable={{{True}}})::
359
  The contents of this setting will be sent as part of the ''From'' header when sending SIP requests.
360
361
=== RTP ===
362
363 28 Luci Stanescu
 '''BonjourAccount.rtp.audio_codec_list''' (type={{{AudioCodecList}}}, default={{{('speex', 'g722', 'g711', 'ilbc', 'gsm')}}})::
364 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.
365 24 Adrian Georgescu
366
 '''BonjourAccount.rtp.srtp_encryption''' (type={{{SRTPEncryption}}}, default={{{'optional'}}})::
367
  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'}}}.
368
369
 '''BonjourAccount.rtp.use_srtp_without_tls''' (type={{{bool}}}, default={{{False}}})::
370 8 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.
371 1 Adrian Georgescu
372 8 Adrian Georgescu
=== TLS ===
373
374 28 Luci Stanescu
 '''BonjourAccount.tls.certificate''' (type={{{Path}}}, default={{{None}}}, nillable={{{True}}})::
375
  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:
376 8 Adrian Georgescu
  {{{
377 28 Luci Stanescu
  BonjourAccount().tls.ca_list.normalized
378 8 Adrian Georgescu
  }}}
379 1 Adrian Georgescu
380 28 Luci Stanescu
 '''BonjourAccount.tls.verify_server''' (type={{{bool}}}, default={{{False}}})::
381 8 Adrian Georgescu
  If this setting is set to {{{True}}}, the middleware will verify the server's certificate when connecting via TLS.
382 1 Adrian Georgescu
383 27 Luci Stanescu
== Architecture ==
384
385 29 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.
386 27 Luci Stanescu
387
The module '''sipsimple.configuration''' contains the main classes of the configuration API. These are:
388
389
 * ConfigurationManager
390
 * SettingsObject
391
 * SettingsGroup
392
 * Setting
393 31 Luci Stanescu
 * SettingsObjectExtension
394 27 Luci Stanescu
395
In addition, the exceptions which make up this package are:
396
397
 * ConfigurationError (base class for all other configuration errors)
398 29 Luci Stanescu
 * ObjectNotFoundError
399 27 Luci Stanescu
400
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].
401 1 Adrian Georgescu
402
=== Configuration Manager ===
403
404 29 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:
405
 * the keys of the dictionary are unicode objects
406
 * the values of the dictionary can be:
407 30 Luci Stanescu
   * the None object (this represents a default value)
408 29 Luci Stanescu
   * unicode objects
409
   * lists of unicode objects
410
   * dictionaries using this specification
411
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, but a simple [wiki:SipConfigurationAPI#FileBackend text file backend] is 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.
412 1 Adrian Georgescu
413 29 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:
414 1 Adrian Georgescu
415
 '''!__init!__'''(''self'')::
416
 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.
417 29 Luci Stanescu
 '''start'''(''self'', '''backend''')::
418
 The start method allows the ConfigurationManager instance to use the specified backend 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.
419
 '''update'''(''self'', '''group''', '''name''', '''data''')::
420
 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.
421
 '''delete'''(''self'', '''group''', '''name''')::
422
 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.
423
 '''get'''(''self'', '''group''', '''name''')::
424
 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.
425
 '''get_names'''(''self'', '''group''')::
426
 Returns a list with all the names of the objects in {{{group}}}. Returns an empty list if the group does not exist.
427 1 Adrian Georgescu
 '''save'''(''self'')::
428 29 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. 
429 1 Adrian Georgescu
430
431
=== SettingsObject ===
432
433
A SettingsObject is used to represent a hierarchy of settings, which are managed via the ConfigurationManager. There are two types of SettingsObject:
434
 * 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.
435
 * 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.
436
437 30 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'''.
438 1 Adrian Georgescu
439
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.
440
441
==== Defining a global SettingsObject ====
442
443 30 Luci Stanescu
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:
444 1 Adrian Georgescu
{{{
445
from sipsimple.configuration import SettingsObject
446
447
class SIPSimpleSettings(SettingsObject):
448 30 Luci Stanescu
    __group__ = 'Global'
449 1 Adrian Georgescu
    __id__ = 'SIPSimple'
450
}}}
451
452
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.
453
454
455
==== Defining a per-id SettingsObject ====
456
457 30 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:
458 1 Adrian Georgescu
{{{
459
from sipsimple.configuration import SettingsObject
460
461
class Account(SettingsObject):
462 30 Luci Stanescu
    __group__ = 'Accounts'
463 1 Adrian Georgescu
    def __init__(self, id):
464
        """Do something each time the Account is loaded"""
465
}}}
466
467
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.
468
469
==== Instance methods of SettingsObjects ====
470
471
 '''save'''(''self'')::
472
 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.
473
 '''delete'''(''self'')::
474
 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.
475
476
==== Notifications ====#SettingsObjectNotifications
477
478
 '''CFGSettingsObjectDidChange'''::
479
 This notification is sent when the save method of a SettingsObject is called. Attributes:
480
 [[BR]]''modified'':[[BR]]
481
 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.
482
483
484
=== Setting ===
485
486
The Setting descriptor is used to describe a setting in SettingsObjects. The following methods are part of the public API of it:
487
 '''!__init!__'''(''self'', '''type''', '''default'''={{{None}}}, '''nillable'''={{{False}}})::
488 30 Luci Stanescu
 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.
489 1 Adrian Georgescu
490
An example of using a setting:
491
{{{
492
from sipsimple.configuration import Setting, SettingsObject
493
494
class SIPSimpleSettings(SettingsObject):
495 30 Luci Stanescu
    __group__ = 'Global'
496 1 Adrian Georgescu
    __id__ = 'SIPSimple'
497
498
    user_agent = Setting(type=str, default='sipsimple %s' % __version__)
499
}}}
500
501 30 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:
502
 * 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.
503
 * int, long and basestring: the type is called using the value as an argument.
504
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.
505 1 Adrian Georgescu
506 30 Luci Stanescu
Saving a setting value is done similarly, according to type. The builtin types which are handled are the same:
507
 * bool: the unicode objects {{{u'true'}}} and {{{u'false}}} are used depending on the value.
508
 * int, long and basestring: {{{unicode}}} is called with the value as the sole argument.
509
For all other types, the {{{__getstate__}}} method is called which should return an appropriate value.
510
511
512 1 Adrian Georgescu
=== SettingsGroup ===
513
514
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:
515
{{{
516
from sipsimple.configuration import Setting, SettingsGroup, SettingsObject
517
518
class TLSSettings(SettingsGroup):
519
    verify_server = Setting(type=bool, default=False)
520
521
class SIPSimpleSettings(SettingsObject):
522 30 Luci Stanescu
    __group__ = 'Global'
523 1 Adrian Georgescu
    __id__ = 'SIPSimple'
524
525
    user_agent = Setting(type=str, default='sipsimple %s' % __version__)
526
527
    tls = TLSSettings
528 31 Luci Stanescu
}}}
529
530
=== SettingsObjectExtension ===
531
532
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:
533
{{{
534
from sipsimple.configuration import Setting, SettingsGroup, SettingsObject
535
536
class TLSSettings(SettingsGroup):
537
    verify_server = Setting(type=bool, default=False)
538
539
class SIPSimpleSettings(SettingsObject):
540
    __group__ = 'Global'
541
    __id__ = 'SIPSimple'
542
543
    user_agent = Setting(type=str, default='sipsimple %s' % __version__)
544
545
    tls = TLSSettings
546
547
class TLSSettingsExtension(TLSSettings):
548
    verify_client = Setting(type=bool, default=True)
549
550
class SIPSimpleSettingsExtension(SettingsObjectExtension):
551
    default_account = Setting(type=str, default=None, nillable=True)
552
553
    tls = TLSSettingsExtension
554
555
SIPSimpleSettings.register_extension(SIPSimpleSettingsExtension)
556 1 Adrian Georgescu
}}}
557
558
=== Backend API ===
559
560 30 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.
561 1 Adrian Georgescu
562
The interface '''sipsimple.configuration.backend.IBackend''' describes the backend:
563 30 Luci Stanescu
 '''load'''()::
564
 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].
565
 '''save'''('''data''')::
566
 Given a dictionary conforming to the definition in this interface, save the data using whatever means employed by the backend implementation.
567 1 Adrian Georgescu
568
569 30 Luci Stanescu
==== FileBackend ====
570 1 Adrian Georgescu
571 30 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:
572 1 Adrian Georgescu
573 30 Luci Stanescu
 '''!__init!__'''(''self'', '''filename''', '''encoding'''={{{'utf-8'}}})::
574
 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.
575 1 Adrian Georgescu
576 30 Luci Stanescu
This object saves the data using a simple text file format with the following syntax:
577
 * 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.
578
 {{{
579
 Accounts:
580
    user@domain:
581
      display_name = User
582
      tls:
583
        certificate =
584
 }}}
585
 * 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:
586
  * None is represented by the absence of a value.
587
  {{{
588
    setting =
589
  }}}
590
  * 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.
591
  {{{
592
    setting1 = value
593
    setting2 = value with spaces
594
    setting3 = "  value with leading and trailing spaces  "
595
    setting4 = value with a line feed\n
596
  }}}
597
  * Lists are represented by unicode strings as described above separated by commas (''','''). Any not-quoted whitespace around the comma is ignored.
598
  {{{
599
    setting = a, b  , c
600
  }}}
601
  * Complex settings can be represented just like a group:
602
  {{{
603
    complex_setting:
604
      field1 = value
605
      field2 = 123
606
  }}}
607
  
608 29 Luci Stanescu
609
== SIPClients Settings==
610 30 Luci Stanescu
611
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.
612 29 Luci Stanescu
613
== General settings ==
614
615
 '''SIPSimpleSettings.user_data_directory''' (type={{{AbsolutePath}}}, default={{{'~/.sipclient}}})::
616
  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.
617
618
=== Audio ===
619
620
 '''SIPSimpleSettings.audio.directory''' (type={{{DataPath}}}, default={{{DataPath('history')}}})::
621
  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:
622
  {{{
623
  SIPSimpleSettings().audio.directory.value
624
  }}}
625
626
=== File Transfer ===
627
628
 '''SIPSimpleSettings.file_transfer.directory''' (type={{{DataPath}}}, default={{{DataPath('file_transfers')}}})::
629
  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:
630
  {{{
631
  SIPSimpleSettings().file_transfer.directory.value
632
  }}}
633
634
=== Logs ===
635
636
 '''SIPSimpleSettings.logs.directory''' (type={{{DataPath}}}, default={{{DataPath('logs')}}})::
637
  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:
638
  {{{
639
  SIPSimpleSettings().logs.directory.value
640
  }}}
641
642
 '''SIPSimpleSettings.logs.trace_sip''' (type={{{bool}}}, default={{{False}}})::
643
  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}}}.
644
645
 '''SIPSimpleSettings.logs.trace_pjsip''' (type={{{bool}}}, default={{{False}}})::
646
  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}}}.
647
648
 '''SIPSimpleSettings.logs.trace_msrp''' (type={{{bool}}}, default={{{False}}})::
649
  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}}}.
650
651
 '''SIPSimpleSettings.logs.trace_xcap''' (type={{{bool}}}, default={{{False}}})::
652
  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}}}.
653
654
=== Sounds ===
655
656
 '''SIPSimpleSettings.sounds.audio_inbound''' (type={{{AbsolutePath}}}, default={{{None}}}, nillable={{{True}}})::
657
  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.
658
659
 '''SIPSimpleSettings.sounds.audio_outbound''' (type={{{AbsolutePath}}}, default={{{None}}}, nillable={{{True}}})::
660
  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.
661
662
 '''SIPSimpleSettings.sounds.file_sent''' (type={{{AbsolutePath}}}, default={{{None}}}, nillable={{{True}}})::
663
  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.
664
665
 '''SIPSimpleSettings.sounds.file_received''' (type={{{AbsolutePath}}}, default={{{None}}}, nillable={{{True}}})::
666
  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.
667
668
 '''SIPSimpleSettings.sounds.message_sent''' (type={{{AbsolutePath}}}, default={{{None}}}, nillable={{{True}}})::
669
  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.
670
671
 '''SIPSimpleSettings.sounds.message_received''' (type={{{AbsolutePath}}}, default={{{None}}}, nillable={{{True}}})::
672
  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.
673
674
== Account ==
675
676
=== Sounds ===
677
678
 '''Account.sounds.audio_inbound''' (type={{{AbsolutePath}}}, default={{{None}}}, nillable={{{True}}})::
679
  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.
680
681
== BonjourAccount ==
682
683
=== Sounds ===
684
685
 '''BonjourAccount.sounds.audio_inbound''' (type={{{AbsolutePath}}}, default={{{None}}}, nillable={{{True}}})::
686 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.