1megaco_user(3)             Erlang Module Definition             megaco_user(3)
2
3
4

NAME

6       megaco_user - Callback module for users of the Megaco application
7

DESCRIPTION

9       This   module  defines  the  callback  behaviour  of  Megaco  users.  A
10       megaco_user compliant callback module must export the  following  func‐
11       tions:
12
13         * handle_connect/2,3
14
15         * handle_disconnect/3
16
17         * handle_syntax_error/3,4
18
19         * handle_message_error/3,4
20
21         * handle_trans_request/3,4
22
23         * handle_trans_long_request/3,4
24
25         * handle_trans_reply/4,5
26
27         * handle_trans_ack/4,5
28
29         * handle_unexpected_trans/3,4
30
31         * handle_trans_request_abort/4,5
32
33         * handle_segment_reply/5,6
34
35       The semantics of them and their exact signatures are explained below.
36
37       The  user_args  configuration parameter which may be used to extend the
38       argument list of the callback functions. For example,  the  handle_con‐
39       nect function takes by default two arguments:
40
41               handle_connect(Handle, Version)
42
43
44       but  if  the  user_args  parameter  is  set  to  a longer list, such as
45       [SomePid,SomeTableRef], the callback function is expected to have these
46       (in this case two) extra arguments last in the argument list:
47
48               handle_connect(Handle, Version, SomePid, SomeTableRef)
49
50
51   Note:
52       Must  of  the functions below has an optional Extra argument (e.g. han‐
53       dle_unexpected_trans/4). The functions which takes this  argument  will
54       be  called  if  and  only  if one of the functions receive_message/5 or
55       process_received_message/5 was called with the Extra argument different
56       than ignore_extra.
57
58

DATA TYPES

60       action_request() = #'ActionRequest'{}
61       action_reply() = #'ActionReply'{}
62       error_desc() = #'ErrorDescriptor'{}
63       segment_no() = integer()
64
65
66       conn_handle() = #megaco_conn_handle{}
67
68       The  record  initially  returned by megaco:connect/4,5. It identifies a
69       "virtual" connection and may be reused after a reconnect (disconnect  +
70       connect).
71
72       protocol_version() = integer()
73
74       Is  the  actual protocol version. In most cases the protocol version is
75       retrieved from the processed message, but there are exceptions:
76
77         * When  handle_connect/2,3  is  triggered  by  an  explicit  call  to
78           megaco:connect/4,5.
79
80         * handle_disconnect/3
81
82         * handle_syntax_error/3
83
84       In  these  cases,  the ProtocolVersion default version is obtained from
85       the static connection configuration:
86
87         * megaco:conn_info(ConnHandle, protocol_version).
88

EXPORTS

90       handle_connect(ConnHandle,   ProtocolVersion)   ->   ok   |   error   |
91       {error,ErrorDescr}
92       handle_connect(ConnHandle,  ProtocolVersion,  Extra)  ->  ok  | error |
93       {error,ErrorDescr}
94
95              Types:
96
97                 ConnHandle = conn_handle()
98                 ProtocolVersion = protocol_version()
99                 ErrorDescr = error_desc()
100                 Extra = term()
101
102              Invoked when a new connection is established
103
104              Connections may either be established by  an  explicit  call  to
105              megaco:connect/4  or  implicitly  at  the  first  invocation  of
106              megaco:receive_message/3.
107
108              Normally a Media Gateway (MG) connects explicitly while a  Media
109              Gateway Controller (MGC) connects implicitly.
110
111              At  the  Media  Gateway  Controller (MGC) side it is possible to
112              reject a connection request (and send a message error  reply  to
113              the  gateway)  by  returning {error, ErrorDescr} or simply error
114              which generates an error descriptor with code 402 (unauthorized)
115              and  reason  "Connection refused by user" (this is also the case
116              for all unknown results, such as exit signals or throw).
117
118              See  note  above  about  the  Extra  argument   in   handle_mes‐
119              sage_error/4.
120
121              handle_connect/3  (with Extra) can also be called as a result of
122              a call to the megaco:connect/5 function  (if  that  function  is
123              called with the Extra argument different than ignore_extra.
124
125       handle_disconnect(ConnHandle, ProtocolVersion, Reason) -> ok
126
127              Types:
128
129                 ConnHandle = conn_handle()
130                 ProtocolVersion = protocol_version()
131                 Reason = term()
132
133              Invoked when a connection is teared down
134
135              The  disconnect  may  either  be  made  explicitly  by a call to
136              megaco:disconnect/2 or implicitly when the  control  process  of
137              the connection dies.
138
139       handle_syntax_error(ReceiveHandle, ProtocolVersion, DefaultED) -> reply
140       | {reply, ED} | no_reply | {no_reply, ED}
141       handle_syntax_error(ReceiveHandle, ProtocolVersion,  DefaultED,  Extra)
142       -> reply | {reply, ED} | no_reply | {no_reply, ED}
143
144              Types:
145
146                 ReceiveHandle = receive_handle()
147                 ProtocolVersion = protocol_version()
148                 DefaultED = error_desc()
149                 ED = error_desc()
150                 Extra = term()
151
152              Invoked when a received message had syntax errors
153
154              Incoming  messages  is delivered by megaco:receive_message/4 and
155              normally decoded successfully. But if the decoding  failed  this
156              function  is  called in order to decide if the originator should
157              get a reply message (reply) or if the reply silently  should  be
158              discarded (no_reply).
159
160              Syntax  errors are detected locally on this side of the protocol
161              and may have many causes, e.g. a malfunctioning transport layer,
162              wrong   encoder/decoder   selected,  bad  configuration  of  the
163              selected encoder/decoder etc.
164
165              The error descriptor defaults to DefaultED, but can be  overrid‐
166              den   with   an   alternate   one  by  returning  {reply,ED}  or
167              {no_reply,ED} instead of reply and no_reply respectively.
168
169              Any other return values (including exit signals  or  throw)  and
170              the DefaultED will be used.
171
172              See   note   above  about  the  Extra  argument  in  handle_syn‐
173              tax_error/4.
174
175       handle_message_error(ConnHandle, ProtocolVersion, ErrorDescr) -> ok
176       handle_message_error(ConnHandle, ProtocolVersion, ErrorDescr, Extra) ->
177       ok
178
179              Types:
180
181                 ConnHandle = conn_handle()
182                 ProtocolVersion = protocol_version()
183                 ErrorDescr = error_desc()
184                 Extra = term()
185
186              Invoked  when  a received message just contains an error instead
187              of a list of transactions.
188
189              Incoming messages is delivered by  megaco:receive_message/4  and
190              successfully  decoded.  Normally  a  message  contains a list of
191              transactions, but it may instead contain an  ErrorDescriptor  on
192              top level of the message.
193
194              Message  errors  are  detected remotely on the other side of the
195              protocol. And you probably don't want to reply to it, but it may
196              indicate  that  you  have outstanding transactions that not will
197              get any response (request -> reply; reply -> ack).
198
199              See  note  above  about  the  Extra  argument   in   handle_mes‐
200              sage_error/4.
201
202       handle_trans_request(ConnHandle,  ProtocolVersion,  ActionRequests)  ->
203       pending() | reply() | ignore_trans_request
204       handle_trans_request(ConnHandle,    ProtocolVersion,    ActionRequests,
205       Extra) -> pending() | reply() | ignore_trans_request
206
207              Types:
208
209                 ConnHandle = conn_handle()
210                 ProtocolVersion = protocol_version()
211                 ActionRequests = [action_request()]
212                 Extra = term()
213                 pending() = {pending, req_data()}
214                 req_data() = term()
215                 reply()  =  {ack_action(),  actual_reply()}  | {ack_action(),
216                 actual_reply(), send_options()}
217                 ack_action() = discard_ack | {handle_ack, ack_data()} | {han‐
218                 dle_pending_ack,     ack_data()}     |    {handle_sloppy_ack,
219                 ack_data()}
220                 actual_reply() = [action_reply()] | error_desc()
221                 ack_data() = term()
222                 send_options() = [send_option()]
223                 send_option() = {reply_timer, megaco_timer()} | {send_handle,
224                 term()} | {protocol_version, integer()}
225                 Extra = term()
226
227              Invoked for each transaction request
228
229              Incoming  messages  is delivered by megaco:receive_message/4 and
230              successfully decoded. Normally a  message  contains  a  list  of
231              transactions  and this function is invoked for each Transaction‐
232              Request in the message.
233
234              This function takes a list of 'ActionRequest'  records  and  has
235              three main options:
236
237                Return ignore_trans_request:
238                  Decide  that  these  action  requests  shall be ignored com‐
239                  pletely.
240
241                Return pending():
242                  Decide that the processing of  these  action  requests  will
243                  take a long time and that the originator should get an imme‐
244                  diate 'TransactionPending' reply as  interim  response.  The
245                  actual processing of these action requests instead should be
246                  delegated to the  the  handle_trans_long_request/3  callback
247                  function with the req_data() as one of its arguments.
248
249                Return reply():
250                  Process   the   action   requests   and   either  return  an
251                  error_descr() indicating some  fatal  error  or  a  list  of
252                  action replies (wildcarded or not).
253
254                  If  for  some  reason megaco is unable to deliver the reply,
255                  the reason for this will be passed to the user via a call to
256                  the  callback function handle_trans_ack, unless ack_action()
257                  = discard_ack.
258
259                  The ack_action() is either:
260
261                  discard_ack:
262                    Meaning that you don't care if the reply  is  acknowledged
263                    or not.
264
265                  {handle_ack,    ack_data()}   |   {handle_ack,   ack_data(),
266                  send_options()}:
267                    Meaning that you want an  immediate  acknowledgement  when
268                    the  other  part receives this transaction reply. When the
269                    acknowledgement   eventually   is   received,   the   han‐
270                    dle_trans_ack/4 callback function will be invoked with the
271                    ack_data() as one of its arguments. ack_data() may be  any
272                    Erlang term.
273
274                  {handle_pending_ack,   ack_data()}   |  {handle_pending_ack,
275                  ack_data(), send_options()}:
276                    This has the same effect as the  above,  if  and  only  if
277                    megaco  has  sent  at  least  one pending message for this
278                    request (during the processing  of  the  request).  If  no
279                    pending message has been sent, then immediate acknowledge‐
280                    ment will not be requested.
281
282                    Note that this only works as specified if  the  sent_pend‐
283                    ing_limit config option has been set to an integer value.
284
285                  {handle_sloppy_ack,     ack_data()}|     {handle_sloppy_ack,
286                  ack_data(), send_options()}:
287                    Meaning that you want an  acknowledgement  sometime.  When
288                    the  acknowledgement  eventually  is  received,  the  han‐
289                    dle_trans_ack/4 callback function will be invoked with the
290                    ack_data()  as one of its arguments. ack_data() may be any
291                    Erlang term.
292
293              Any other return values (including exit signals or  throw)  will
294              result  in  an  error descriptor with code 500 (internal gateway
295              error) and the module name (of the callback module) as reason.
296
297              See   note   above   about   the   Extra   argument   in    han‐
298              dle_trans_request/4.
299
300       handle_trans_long_request(ConnHandle,   ProtocolVersion,   ReqData)  ->
301       reply()
302       handle_trans_long_request(ConnHandle, ProtocolVersion, ReqData,  Extra)
303       -> reply()
304
305              Types:
306
307                 ConnHandle = conn_handle()
308                 ProtocolVersion = protocol_version()
309                 ReqData = req_data()
310                 Extra = term()
311                 req_data() = term()
312                 reply()  =  {ack_action(),  actual_reply()}  | {ack_action(),
313                 actual_reply(), send_options()}
314                 ack_action() = discard_ack | {handle_ack, ack_data()} | {han‐
315                 dle_sloppy_ack, ack_data()}
316                 actual_reply() = [action_reply()] | error_desc()
317                 ack_data() = term()
318                 send_options() = [send_option()]
319                 send_option() = {reply_timer, megaco_timer()} | {send_handle,
320                 term()} | {protocol_version, integer()}
321                 Extra = term()
322
323              Optionally invoked for a time consuming transaction request
324
325              If this function gets invoked or not is controlled by the  reply
326              from  the  preceding  call  to  handle_trans_request/3. The han‐
327              dle_trans_request/3 function may decide to  process  the  action
328              requests itself or to delegate the processing to this function.
329
330              The  req_data()  argument  to  this  function is the Erlang term
331              returned by handle_trans_request/3.
332
333              Any other return values (including exit signals or  throw)  will
334              result  in  an  error descriptor with code 500 (internal gateway
335              error) and the module name (of the callback module) as reason.
336
337              See   note   above   about   the   Extra   argument   in    han‐
338              dle_trans_long_request/4.
339
340       handle_trans_reply(ConnHandle,  ProtocolVersion,  UserReply, ReplyData)
341       -> ok
342       handle_trans_reply(ConnHandle, ProtocolVersion,  UserReply,  ReplyData,
343       Extra) -> ok
344
345              Types:
346
347                 ConnHandle = conn_handle()
348                 ProtocolVersion = protocol_version()
349                 UserReply = success() | failure()
350                 success() = {ok, result()}
351                 result() = transaction_result() | segment_result()
352                 transaction_result() = action_reps()
353                 segment_result()     =     {segment_no(),     last_segment(),
354                 action_reps()}
355                 action_reps() = [action_reply()]
356                 failure() = {error, reason()} | {error, ReplyNo, reason()}
357                 reason()  =   transaction_reason()   |   segment_reason()   |
358                 user_cancel_reason() | send_reason() | other_reason()
359                 transaction_reason() = error_desc()
360                 segment_reason()     =     {segment_no(),     last_segment(),
361                 error_desc()}
362                 other_reason() =  timeout  |  {segment_timeout,  missing_seg‐
363                 ments()} | exceeded_recv_pending_limit | term()
364                 last_segment() = bool()
365                 missing_segments() = [segment_no()]
366                 user_cancel_reason()   =  {user_cancel,  reason_for_user_can‐
367                 cel()}
368                 reason_for_user_cancel() = term()
369                 send_reason() =  send_cancelled_reason()  |  send_failed_rea‐
370                 son()
371                 send_cancelled_reason()   =   {send_message_cancelled,   rea‐
372                 son_for_send_cancel()}
373                 reason_for_send_cancel() = term()
374                 send_failed_reason()     =     {send_message_failed,     rea‐
375                 son_for_send_failure()}
376                 reason_for_send_failure() = term()
377                 ReplyData = reply_data()
378                 ReplyNo = integer() > 0
379                 reply_data() = term()
380                 Extra = term()
381
382              Optionally invoked for a transaction reply
383
384              The  sender of a transaction request has the option of deciding,
385              whether the originating Erlang process should synchronously wait
386              (megaco:call/3)  for  a  reply  or if the message should be sent
387              asynchronously (megaco:cast/3) and the processing of  the  reply
388              should be delegated this callback function.
389
390              Note  that if the reply is segmented (split into several smaller
391              messages; segments), then some extra info, segment number and an
392              indication  if all segments of a reply has been received or not,
393              is also included in the UserReply.
394
395              The ReplyData defaults to megaco:lookup(ConnHandle, reply_data),
396              but  may  be  explicitly overridden by a megaco:cast/3 option in
397              order to forward info about the calling context of the originat‐
398              ing process.
399
400              At success(), the UserReply either contains:
401
402                * A  list  of  'ActionReply' records possibly containing error
403                  indications.
404
405                * A tuple of size three containing: the  segment  number,  the
406                  last  segment  indicator and finally a list of 'ActionReply'
407                  records possibly containing error indications.  This  is  of
408                  course only possible if the reply was segmented.
409
410              failure() indicates an local or external error and can be one of
411              the following:
412
413                * A transaction_reason(), indicates that the remote  user  has
414                  replied with an explicit transactionError.
415
416                * A  segment_reason(),  indicates  that  the  remote  user has
417                  replied with an explicit transactionError for this  segment.
418                  This is of course only possible if the reply was segmented.
419
420                * A  user_cancel_reason(), indicates that the request has been
421                  canceled by the user. reason_for_user_cancel() is the reason
422                  given in the call to the cancel function.
423
424                * A   send_reason(),   indicates  that  the  transport  module
425                  send_message function did not send the message.  The  reason
426                  for this can be:
427
428                  * send_cancelled_reason() - the message sending was deliber‐
429                    ately cancelled. reason_for_send_cancel()  is  the  reason
430                    given in the cancel return from the send_message function.
431
432                  * send_failed_reason()  - an error occurred while attempting
433                    to send the message.
434
435                * An other_reason(), indicates some other error such as:
436
437                  * timeout - the reply failed to arrive  before  the  request
438                    timer expired.
439
440                  * {segment_timeout,  missing_segments()}  - one or more seg‐
441                    ments was not delivered before the expire of  the  segment
442                    timer.
443
444                  * exceeded_recv_pending_limit   -   the  pending  limit  was
445                    exceeded for this request.
446
447              See note above about the Extra argument in handle_trans_reply/5.
448
449       handle_trans_ack(ConnHandle, ProtocolVersion, AckStatus, AckData) -> ok
450       handle_trans_ack(ConnHandle,   ProtocolVersion,   AckStatus,   AckData,
451       Extra) -> ok
452
453              Types:
454
455                 ConnHandle = conn_handle()
456                 ProtocolVersion = protocol_version()
457                 AckStatus = ok | {error, reason()}
458                 reason()  = user_cancel_reason() | send_reason() | other_rea‐
459                 son()
460                 user_cancel_reason()  =  {user_cancel,   reason_for_user_can‐
461                 cel()}
462                 send_reason()  =  send_cancelled_reason()  | send_failed_rea‐
463                 son()
464                 send_cancelled_reason()   =   {send_message_cancelled,   rea‐
465                 son_for_send_cancel()}
466                 reason_for_send_cancel() = term()
467                 send_failed_reason()     =     {send_message_failed,     rea‐
468                 son_for_send_failure()}
469                 reason_for_send_failure() = term()
470                 other_reason() = term()
471                 AckData = ack_data()
472                 ack_data() = term()
473                 Extra = term()
474
475              Optionally invoked for a transaction acknowledgement
476
477              If this function gets invoked or not, is controlled by the reply
478              from  the  preceding  call  to  handle_trans_request/3. The han‐
479              dle_trans_request/3 function may decide to  return  {handle_ack,
480              ack_data()}  or {handle_sloppy_ack, ack_data()} meaning that you
481              need an immediate acknowledgement of the  reply  and  that  this
482              function should be invoked to handle the acknowledgement.
483
484              The  ack_data()  argument  to  this  function is the Erlang term
485              returned by handle_trans_request/3.
486
487              If the AckStatus is ok, it is indicating that  this  is  a  true
488              acknowledgement of the transaction reply.
489
490              If  the  AckStatus  is {error, Reason}, it is an indication that
491              the acknowledgement or even the reply  (for  which  this  is  an
492              acknowledgement)  was  not  delivered,  but there is no point in
493              waiting any longer for it to arrive. This happens when:
494
495                reply_timer:
496                  The reply_timer eventually times out.
497
498                reply send failure:
499                  When  megaco   fails   to   send   the   reply   (see   han‐
500                  dle_trans_reply), for whatever reason.
501
502                cancel:
503                  The  user  has  explicitly  cancelled  the wait (megaco:can‐
504                  cel/2).
505
506              See note above about the Extra argument in handle_trans_ack/5.
507
508       handle_unexpected_trans(ConnHandle, ProtocolVersion, Trans) -> ok
509       handle_unexpected_trans(ConnHandle, ProtocolVersion, Trans,  Extra)  ->
510       ok
511
512              Types:
513
514                 ConnHandle = conn_handle()
515                 ProtocolVersion = protocol_version()
516                 Trans  =  #'TransactionPending'{}  |  #'TransactionReply'{} |
517                 #'TransactionResponseAck'{}
518                 Extra = term()
519
520              Invoked when a unexpected message is received
521
522              If a reply to a request is not  received  in  time,  the  megaco
523              stack  removes  all info about the request from its tables. If a
524              reply should arrive after this has been done the app has no  way
525              of  knowing where to send this message. The message is delivered
526              to the "user" by calling this function on the  local  node  (the
527              node which has the link).
528
529              See   note  above  about  the  Extra  argument  in  handle_unex‐
530              pected_trans/4.
531
532       handle_trans_request_abort(ConnHandle, ProtocolVersion,  TransNo,  Pid)
533       -> ok
534       handle_trans_request_abort(ConnHandle,  ProtocolVersion,  TransNo, Pid,
535       Extra) -> ok
536
537              Types:
538
539                 ConnHandle = conn_handle()
540                 ProtocolVersion = protocol_version()
541                 TransNo = integer()
542                 Pid = undefined | pid()
543                 Extra = term()
544
545              Invoked when a transaction request has been aborted
546
547              This function is invoked if the originating  pending  limit  has
548              been  exceeded.  This  usually  means  that  a request has taken
549              abnormally long time to complete.
550
551              See   note   above   about   the   Extra   argument   in    han‐
552              dle_trans_request_abort/5.
553
554       handle_segment_reply(ConnHandle,  ProtocolVersion, TransNo, SegNo, Seg‐
555       Compl) -> ok
556       handle_segment_reply(ConnHandle, ProtocolVersion, TransNo, SegNo,  Seg‐
557       Compl, Extra) -> ok
558
559              Types:
560
561                 ConnHandle = conn_handle()
562                 ProtocolVersion = protocol_version()
563                 TransNo = integer()
564                 SegNo = integer()
565                 SegCompl = asn1_NOVALUE | 'NULL'
566                 Extra = term()
567
568              This  function  is called when a segment reply has been received
569              if the segment_reply_ind config option has been set to true.
570
571              This is in effect a progress report.
572
573              See  note  above  about  the  Extra  argument   in   handle_seg‐
574              ment_reply/6.
575
576
577
578Ericsson AB                      megaco 3.19.5                  megaco_user(3)
Impressum