Browse code

yet more documentation...

git-svn-id: http://svn.berlios.de/svnroot/repos/sems/trunk@267 8eb893ce-cfd4-0310-b710-fb5ebe64c474

Stefan Sayer authored on 07/03/2007 22:37:46
Showing 9 changed files
1 1
new file mode 100644
... ...
@@ -0,0 +1,2 @@
1
+doc:
2
+	make -C ../core doc
... ...
@@ -1,6 +1,6 @@
1
-******************************
2
-* Announcement Server Module *
3
-******************************
1
+*******************************************************
2
+* Pre-Call announcement with B2BUA Application Module *
3
+*******************************************************
4 4
 
5 5
 Description:
6 6
 ------------
... ...
@@ -11,4 +11,6 @@ It searches for files to play following these rules:
11 11
  1) [AnnouncePath]/[Domain]/[User].wav
12 12
  2) [AnnouncePath]/[User].wav
13 13
 
14
-That's it.
14
+Then it connects the caller to the r_uri in Back-To-Back 
15
+User Agent (B2BUA) mode, thus staying in the signalling path 
16
+of the call.
... ...
@@ -1,8 +1,8 @@
1 1
 Announcement then call transfer 
2 2
 
3 3
 This application plays an announcement and then REFERs the caller
4
-to either the uri configured in P-Refer-To header, or if his is not
5
-configured, the request URI of the first INVITE.
4
+to either the uri configured in the Refer-To session parameter, 
5
+or, if his is not set, the request URI of the first INVITE.
6 6
 
7 7
 If refer is not accepted, succeeds, or fails, a BYE is sent.
8 8
 
... ...
@@ -10,7 +10,7 @@ Example ser configuration appends:
10 10
 
11 11
 #appends: parameter for announce_transfer
12 12
 modparam( "tm", "tw_append",
13
-   "announce_transfer_headers:P-Refer-To=avp[$refer_to]")
13
+   "announce_transfer_headers:P-Iptel-Param=avp[$refer_to]")
14 14
 
15 15
 # appends for REFER NOTIFYs
16 16
 modparam( "tm", "tw_append",
... ...
@@ -36,7 +36,7 @@ Example of invoking announce_transfer within route:
36 36
 	} 
37 37
 
38 38
 	if (method == "INVITE") {
39
-		avp_write("sip:callme@example.com","$refer_to");
39
+		avp_write("Refer-To=sip:callme@example.com","$refer_to");
40 40
 		if (!t_write_unix("/tmp/sems_sock","announce_transfer/announce_transfer_headers")){
41 41
 			log("could not contact announce_transfer\n");
42 42
 			t_reply("500","could not contact media server");	
... ...
@@ -11,9 +11,10 @@ in an early session: it replies to an invite with
11 11
 and finally replies the request with a response (by default
12 12
 404 Not found ).
13 13
 
14
-Additional Headers:
15
-   P-Final-Reply-Code     integer (ex. P-Final-Reply-Code:405 )
16
-   P-Final-Reply-Reason   string (e.g. P-Final-Reply-Reason:Prohibited)
14
+Session Parameters:
15
+   Final-Reply-Code     integer (e.g. Final-Reply-Code=405 )
16
+   Final-Reply-Reason   string  (e.g. Final-Reply-Reason=Prohibited)
17
+
17 18
 
18 19
 
19 20
 It searches for files to play following these rules:
... ...
@@ -61,10 +62,10 @@ loadmodule "modules/avpops/avpops.so"
61 62
 # add value to ;lr param to make some broken UAs happy
62 63
 modparam("rr", "enable_full_lr", 1)
63 64
 
64
-modparam( "avpops", "avp_aliases", "early_code=i:66 ; early_reason=i:67" )
65
+modparam( "avpops", "avp_aliases", "sess_params=i:66" )
65 66
 
66 67
 # this is to be appended to the invite
67
-modparam("tm", "tw_append","early_headers:P-Final-Reply-Code=avp[$early_code];P-Final-Reply-Reason=avp[$early_reason]")
68
+modparam("tm", "tw_append","early_headers:P-Iptel-Param=avp[$sess_params]")
68 69
 
69 70
 # -------------------------  request routing logic -------------------
70 71
 # main routing logic
... ...
@@ -112,8 +113,8 @@ route{
112 113
 
113 114
            	if (method == "INVITE") {
114 115
 
115
-           		avp_write("405", "$early_code");
116
-           		avp_write("Prohiboted", "$early_reason");
116
+           		avp_write("Final-Reply-Code=405;Final-Reply-Reason=Prohiboted", 
117
+                                  "$sess_param");
117 118
 
118 119
             		if(!t_write_unix("/tmp/sems_sock","early_announce/early_headers")){
119 120
                 		log("could not contact early_announce\n");
... ...
@@ -88,3 +88,99 @@ Troubleshooting:
88 88
   Look at the debug information present at start time, some libraries 
89 89
   may be missing in which case you should set the proper PYTHONPATH
90 90
   before starting SEMS.
91
+
92
+
93
+IVR API quickref:
94
+-----------------
95
+
96
+
97
+ globals: getHeader(String headers, String name)
98
+             get header with name from headers
99
+
100
+          getSessionParam(String headers, String name)
101
+            get session parameter with name from headers
102
+            (parameter from P-Iptel-Param)
103
+
104
+          log(String str)
105
+              log using sems' log facility
106
+
107
+          createThread(Callable thread)
108
+              create a thread. Only to be used on module 
109
+              initialization code!
110
+
111
+class IvrDialogBase:
112
+
113
+    # Event handlers
114
+    def onStart(self): # SIP dialog start
115
+        pass
116
+
117
+    def onBye(self): # SIP dialog is BYEd
118
+        pass
119
+    
120
+    def onSessionStart(self): # audio session start
121
+        pass
122
+
123
+    def onEmptyQueue(self): # audio queue is empty
124
+        pass
125
+    
126
+    def onDtmf(self,key,duration): # received DTMF
127
+        pass
128
+
129
+
130
+    # Session control
131
+    def stopSession(self): # stop everything
132
+        pass
133
+
134
+    def bye(self): # BYEs (or CANCELs) the SIP dialog
135
+        pass
136
+
137
+
138
+    # Media control
139
+    def enqueue(self,audio_play,audio_rec): # add something to the playlist
140
+        pass
141
+
142
+    def flush(self): # flushes playlist
143
+        pass
144
+
145
+    # Call datas / control
146
+
147
+    # get only property wrapping AmSipDialog AmSession::dlg.
148
+    # only its properties should be exposed.
149
+    dialog
150
+
151
+    # B2BUA
152
+
153
+    # if true, traffic will be relayed
154
+    # transaprently to the other side
155
+    # if this is 'True' at the beginning 
156
+    # of the session, the Caller's INVITE
157
+    # will be relayed to the callee, without
158
+    # having to use connectCallee()
159
+    B2BMode = False
160
+
161
+    # call given party as (new) callee
162
+    # if remote_party and remote_uri are empty (None),
163
+    # we will connect to the callee of the initial caller request
164
+    def connectCallee(self,remote_party,remote_uri):
165
+        pass
166
+
167
+    # terminate the callee's call
168
+    def terminateOtherLeg(self):
169
+        pass
170
+
171
+    # terminate our call
172
+    def terminateLeg(self):
173
+        pass
174
+
175
+    # start a new audio session with the caller
176
+    # sends a re-INVITE if needed.
177
+    def connectAudio(self):
178
+        pass
179
+
180
+    # end the audio session
181
+    # sends a re-INVITE if needed to reconnect to the current callee
182
+    def disconnectAudio(self):
183
+    	pass
184
+
185
+    # B2BUA Event handlers
186
+    # some other handlers...
... ...
@@ -21,16 +21,16 @@ mailbox_query.conf:
21 21
    wav_dir              -    directory which contains wav files for
22 22
                              menu
23 23
 
24
-Invocation Parameters (Headers of the INVITE)
25
-============================================
24
+Session Parameters (In P-Iptel-Param headers)
25
+=============================================
26 26
 
27 27
 mailbox:
28 28
 
29
- P-Mailbox-URL      -  IMAP URL to the mailbox
29
+ Mailbox-URL      -  IMAP URL to the mailbox
30 30
 
31 31
 mailbox_query:
32 32
 
33
- P-Mailbox-URL      -  IMAP URL to the mailbox
33
+ Mailbox-URL      -  IMAP URL to the mailbox
34 34
 
35 35
 
36 36
 
... ...
@@ -38,13 +38,13 @@ Example for ser.cfg
38 38
 ===================
39 39
 
40 40
 # appends for INVITE to mailbox
41
-modparam("tm", "tw_append", "mailbox_headers:P-Mailbox-URL=avp[$mailbox_url]")
41
+modparam("tm", "tw_append", "mailbox_headers:P-Iptel-Param=avp[$mailbox_url]")
42 42
 
43 43
 
44 44
 ...
45 45
         # replace this with a function that loads imap url e.g. from DB
46 46
         # into $mailbox_url AVP
47
-		avp_write("imap://user:password@imapserver:143/INBOX",
47
+		avp_write("Mailbox-URL=imap://user:password@imapserver:143/INBOX",
48 48
                       "$mailbox_url");
49 49
 
50 50
 		if (!t_write_unix("/tmp/sems_sock","mailbox/mailbox_headers")){
... ...
@@ -26,8 +26,8 @@ Authentication Modes:
26 26
  properly support re-Invite (updating of contact, and session, as specified 
27 27
  in RFC3261).
28 28
 
29
- The transfer request sent out has two headers, which are needed by the 
30
- entity taking the call: 
31
-  P-Transfer-RR  : route set of the call
32
-  P-Transfer-NH  : next hop 
29
+ The transfer request sent out has two session parameters (set in
30
+ P-Iptel-Param header), which are needed by the entity taking the call: 
33 31
 
32
+  Transfer-RR  : route set of the call
33
+  Transfer-NH  : next hop 
34 34
new file mode 100644
... ...
@@ -0,0 +1,26 @@
1
+py_sems Readme 
2
+
3
+  py_sems is aimed at integrating as much functionnalities
4
+  from the core as possible into python driven applications 
5
+  (not necessarily IVRs), in a more easy way. The classes can 
6
+  then just be used as in C++.
7
+
8
+  This plug-in uses the sip4 package included in debian.
9
+  Please refer to http://www.riverbankcomputing.co.uk/sip/
10
+  for more informations on the binding generator.
11
+  Please note that you do not need it, if you just want to compile
12
+  SEMS. You will need it first if you want to generate more classes.
13
+
14
+  The version included is 4.1.1. If you generate some files using
15
+  a new version of sip4, update or remove sip.h in the apps/py_sems/sip 
16
+  directory.
17
+
18
+  Example applications for py_sems can be found in 
19
+  apps/examples/py_sems_ex.
20
+
21
+
22
+  This py_sems Readme file is a stub. You can help the community by 
23
+  sending a patch with more information to the semsdev list
24
+  (semsdev@iptel.org).
25
+
26
+
... ...
@@ -1,5 +1,5 @@
1 1
 /* \file This file generates Doxygen pages from files in the /doc
2
- directory 
2
+ *  directory 
3 3
  */
4 4
 
5 5
 /*! \page index SEMS Documentation 
... ...
@@ -38,7 +38,7 @@
38 38
  */
39 39
 
40 40
 /*! \page changelog Changelog (from 0.10.0-rc1 onwards)
41
- * CHANGELOG for SEMS which is from 0.10.0-rc1 onwards 
41
+ * CHANGELOG for SEMS from 0.10.0-rc1 onwards 
42 42
  * \verbinclude CHANGELOG
43 43
  * 
44 44
  */
... ...
@@ -68,7 +68,10 @@
68 68
  */
69 69
 
70 70
 /*! \page sems.conf.sample SEMS core configuration parameters
71
- * core/sems.conf.sample
71
+ * <p>The sample configuration file core/sems.conf.sample 
72
+ * explains all core configuration parameters. </p><p>If there is no 
73
+ * configuration file present, 'make install' installs this file
74
+ * into the default location.</p>
72 75
  * 
73 76
  * \verbinclude sems.conf.sample
74 77
  * 
... ...
@@ -134,8 +137,11 @@
134 137
  * <ul><li>  \ref ModuleDoc_pin_collect </li></ul>
135 138
  *
136 139
  * 
137
- * \section IVR: Python Scripting application 
140
+ * \section Scripting SEMS with Python 
138 141
  *
142
+ * There are two application modules which embed a python interpreted into 
143
+ * SEMS: the <i>ivr</i> module and the <i>py_sems</i> module.
144
+ * 
139 145
  * The <i>ivr</i> module plugin embeds a python interpreter into SEMS. In it, 
140 146
  * applications written in python can be run (<i>mailbox</i>, <i>conf_auth</i>,
141 147
  * <i>pin_collect</i> for example) and new applications can be prototyped and 
... ...
@@ -143,77 +149,144 @@
143 149
  *
144 150
  * <ul><li> \ref ModuleDoc_ivr  </li></ul>
145 151
  * 
152
+ * The <i>ivr</i> module has a simple to use, yet limited API, which uses 
153
+ * hand-written wrappers for the python bindings.
154
+ *
155
+ * <i>py_sems</i> uses a binding generator to make python classes from the
156
+ * SEMS core C++ classes, thus exposing a lot more functionality natively 
157
+ * to python:
158
+ *
159
+ * <ul><li> \ref ModuleDoc_py_sems  </li></ul>
160
+ * 
146 161
  */
147 162
 
148 163
 /*! \page ModuleDoc_ann_b2b Module Documentation: ann_b2b Application 
149 164
  *  \section Readme_ann_b2b Readme file
150 165
  *  \verbinclude Readme.ann_b2b
166
+ *  
167
+ *  \section Links
168
+ *  Back to \ref AppDoc
151 169
  */
152 170
 
153 171
 /*! \page ModuleDoc_announce_auth Module Documentation: announce_auth Application 
154 172
  *  \section Readme_announce_auth Readme file
155 173
  *  \verbinclude Readme.announce_auth
174
+ *  
175
+ *  \section Links
176
+ *  Back to \ref AppDoc
156 177
  */
157 178
 
158 179
 /*! \page ModuleDoc_announce_transfer Module Documentation: announce_transfer Application 
159 180
  *  \section Readme_announce_transfer Readme file
160 181
  *  \verbinclude Readme.announce_transfer
161
- */
162
-/*! \page ModuleDoc_ann_b2b Module Documentation: ann_b2b Application 
163
- *  \section Readme_ann_b2b Readme file
164
- *  \verbinclude Readme.ann_b2b
182
+ *  
183
+ *  \section Links
184
+ *  Back to \ref AppDoc
165 185
  */
166 186
 
167 187
 /*! \page ModuleDoc_announcement Module Documentation: announcement Application 
168 188
  *  \section Readme_announcement Readme file
169 189
  *  \verbinclude Readme.announcement
190
+ *  
191
+ *  \section Links
192
+ *  Back to \ref AppDoc
170 193
  */
171 194
 
172 195
 /*! \page ModuleDoc_conference Module Documentation: conference Application 
173 196
  *  \section Readme_conference Readme file
174 197
  *  \verbinclude Readme.conference
198
+ *  
199
+ *  \section Links
200
+ *  Back to \ref AppDoc
175 201
  */
176 202
 
177 203
 /*! \page ModuleDoc_early_announce Module Documentation: early_announce Application 
178 204
  *  \section Readme_early_announce Readme file
179 205
  *  \verbinclude Readme.early_announce
206
+ *  
207
+ *  \section Links
208
+ *  Back to \ref AppDoc
180 209
  */
181 210
 
182 211
 /*! \page ModuleDoc_voicemail Module Documentation: voicemail Application 
183 212
  *  \section Readme_voicemail Readme file
184 213
  *  \verbinclude Readme.voicemail
214
+ *  
215
+ *  \section Links
216
+ *  Back to \ref AppDoc
185 217
  */
186 218
 
187 219
 /*! \page ModuleDoc_mailbox Module Documentation: mailbox Application 
188 220
  *  \section Readme_mailbox Readme file
189 221
  *  \verbinclude Readme.mailbox
222
+ *  
223
+ *  \section Links
224
+ *  Back to \ref AppDoc
190 225
  */
191 226
 
192 227
 /*! \page ModuleDoc_ivr Module Documentation: ivr Application 
193 228
  *  \section Readme_ivr Readme file
194 229
  *  \verbinclude Readme.ivr
230
+ *  
231
+ *  \section Links
232
+ *  Back to \ref AppDoc
233
+ */
234
+
235
+/*! \page ModuleDoc_py_sems Module Documentation: py_sems Application 
236
+ *  \section Readme_py_sems Readme file
237
+ *  \verbinclude Readme.py_sems
238
+ *  
239
+ *  \section Links
240
+ *  Back to \ref AppDoc
195 241
  */
196 242
 
197 243
 /*! \page ModuleDoc_uac_auth Module Documentation: uac_auth component 
198 244
  *  \section Readme_uac_auth Readme file
199 245
  *  \verbinclude Readme.uac_auth
246
+ *  
247
+ *  \section Links
248
+ *  Back to \ref AppDoc
200 249
  */
201 250
 
202 251
 /*! \page ModuleDoc_registrar_client Module Documentation: registrar_client component 
203 252
  *  \section Readme_registrar_client Readme file
204 253
  *  \verbinclude Readme.registrar_client
254
+ *  
255
+ *  \section Links
256
+ *  Back to \ref AppDoc
205 257
  */
206 258
 
207 259
 /*! \page ModuleDoc_mp3plugin Module Documentation: mp3 file writer audio plugin
208 260
  *  \section Readme_mp3plugin Readme file
209 261
  *  \verbinclude Readme.mp3plugin
262
+ *  
263
+ *  \section Links
264
+ *  Back to \ref AppDoc
210 265
  */
211 266
 
212 267
 /*! \page ModuleDoc_iLBC Module Documentation: iLBC codec plugin
213 268
  *  \section Readme_iLBC Readme file
214 269
  *  \verbinclude Readme.iLBC
270
+ *  
271
+ *  \section Links
272
+ *  Back to \ref AppDoc
215 273
  */
216 274
 
275
+/*! \page ModuleDoc_conf_auth Module Documentation: conf_auth Application
276
+ *  \section Readme_conf_auth Readme file
277
+ *  \verbinclude Readme.conf_auth
278
+ *  
279
+ *  \section Links
280
+ *  Back to \ref AppDoc
281
+ */
282
+
283
+/*! \page ModuleDoc_pin_collect Module Documentation: pin_collect Application 
284
+ *  \section Readme_pin_collect Readme file
285
+ *  \verbinclude Readme.pin_collect
286
+ *  
287
+ *  \section Links
288
+ *  Back to \ref AppDoc
289
+ */
217 290
 
218 291
 
219 292
 /*! \page ComponentDoc Component Modules Documentation