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

NAME

6       megaco - Main API of the Megaco application
7

DESCRIPTION

9       Interface module for the Megaco application
10

DATA TYPES

12       megaco_mid() = ip4Address() | ip6Address() |
13                      domainName() | deviceName() |
14                      mtpAddress()
15       ip4Address() = #'IP4Address'{}
16       ip6Address() = #'IP6Address'{}
17       domainName() = #'DomainName'{}
18       deviceName() = pathName()
19       pathName()   = ia5String(1..64)
20       mtpAddress() = octetString(2..4)
21
22       action_request() = #'ActionRequest'{}
23       action_reply() = #'ActionReply'{}
24       error_desc() = #'ErrorDescriptor'{}
25       transaction_reply() = #'TransactionReply'{}
26       segment_no() = integer()
27
28       resend_indication() = flag | boolean()
29
30       property_parm() = #'PropertyParm'{}
31       property_group() = [property_parm()]
32       property_groups() = [property_group()]
33
34       sdp() = sdp_c() | sdp_o() | sdp_s() | sdp_i() | sdp_u() |
35               sdp_e() | sdp_p() | sdp_b() | sdp_z() | sdp_k() |
36               sdp_a() | sdp_a_rtpmap() | sdp_a_ptime() |
37               sdp_t() | sdp_r() | sdp_m()
38       sdp_v() = #megaco_sdp_v{} (Protocol version)
39       sdp_o() = #megaco_sdp_o{} (Owner/creator and session identifier)
40       sdp_s() = #megaco_sdp_s{} (Session name)
41       sdp_i() = #megaco_sdp_i{} (Session information)
42       sdp_u() = #megaco_sdp_u{} (URI of description)
43       sdp_e() = #megaco_sdp_e{} (Email address)
44       sdp_p() = #megaco_sdp_p{} (Phone number)
45       sdp_c() = #megaco_sdp_c{} (Connection information)
46       sdp_b() = #megaco_sdp_b{} (Bandwidth information)
47       sdp_k() = #megaco_sdp_k{} (Encryption key)
48       sdp_a() = #megaco_sdp_a{} (Session attribute)
49       sdp_a_rtpmap() = #megaco_sdp_a_rtpmap{}
50       sdp_a_ptime() = #megaco_sdp_a_ptime{}
51       sdp_a_quality() = #megaco_sdp_a_quality{}
52       sdp_a_fmtp() = #megaco_sdp_a_fmtp{}
53       sdp_z() = #megaco_sdp_z{} (Time zone adjustment)
54       sdp_t() = #megaco_sdp_t{} (Time the session is active)
55       sdp_r() = #megaco_sdp_r{} (Repeat times)
56       sdp_m() = #megaco_sdp_m{} (Media name and transport address)
57       sdp_property_parm() = sdp() | property_parm()
58       sdp_property_group() = [sdp_property_parm()]
59       sdp_property_groups() = [sdp_property_group()]
60
61       megaco_timer() = infinity | integer() >= 0 | megaco_incr_timer()
62       megaco_incr_timer() = #megaco_incr_timer{}
63
64
65       The record megaco_incr_timer contains the following fields:
66
67         wait_for = integer() >= 0:
68           The actual timer time.
69
70         factor = integer() >= 0:
71           The factor when calculating the new timer time (wait_for).
72
73         incr = integer():
74           The increment value when calculating the new timer time (wait_for).
75           Note that this value can be negative and that a timer  restart  can
76           therefor  lead to a wait_for value of zero! It is up to the user to
77           be aware of the consequences of a wait_for value of zero.
78
79         max_retries = infinity | infinity_restartable | integer() >= 0:
80           The maximum number of repetitions of the timer.
81
82           There is a special case for this field. When  the  max_retries  has
83           the   value  infinity_restartable,  it  means  that  the  timer  is
84           restartable as long as some external event occurs (e.g. receipt  of
85           a  pending  message  for  instance).  But  the  timer will never be
86           restarted "by itself", i.e. when the timer  expires  (whatever  the
87           timeout  time), so does the timer. Whenever the timer is restarted,
88           the timeout time will be calculated in the usual way! Also, as men‐
89           tioned  above,  beware the consequences of setting the value to in‐
90           finity if incr has been set to an negative value.
91

EXPORTS

93       start() -> ok | {error, Reason}
94
95              Types:
96
97                 Reason = term()
98
99              Starts the Megaco application
100
101              Users    may    either    explicitly    be    registered    with
102              megaco:start_user/2  and/or  be statically configured by setting
103              the application environment variable 'users' to a list of {User‐
104              Mid,  Config}  tuples.  See the function megaco:start_user/2 for
105              details.
106
107       stop() -> ok | {error, Reason}
108
109              Types:
110
111                 Reason = term()
112
113              Stops the Megaco application
114
115       start_user(UserMid, Config) -> ok | {error, Reason}
116
117              Types:
118
119                 UserMid = megaco_mid()
120                 Config = [{user_info_item(), user_info_value()}]
121                 Reason = term()
122
123              Initial configuration of a user
124
125              Requires the megaco application to be started. A user is  either
126              a  Media  Gateway  (MG) or a Media Gateway Controller (MGC). One
127              Erlang node may host many users.
128
129              A user is identified by its  UserMid,  which  must  be  a  legal
130              Megaco MID.
131
132              Config is a list of {Item, Value} tuples. See megaco:user_info/2
133              about which items and values that are valid.
134
135       stop_user(UserMid) -> ok | {error, Reason}
136
137              Types:
138
139                 UserMid = megaco_mid()
140                 Reason = term()
141
142              Delete the configuration of a user
143
144              Requires that the user does not have any active connection.
145
146       user_info(UserMid) -> [{Item, Value}]
147       user_info(UserMid, Item) -> Value | exit(Reason)
148
149              Types:
150
151                 Handle = user_info_handle()
152                 UserMid = megaco_mid()
153                 Item = user_info_item()
154                 Value = user_info_value()
155                 Reason = term()
156
157              Lookup user information
158
159              The following Item's are valid:
160
161                connections:
162                  Lists all active connections for this user. Returns  a  list
163                  of megaco_conn_handle records.
164
165                receive_handle:
166                  Construct a megaco_receive_handle record from user config
167
168                trans_id:
169                  Current transaction id.
170
171                  A  positive integer or the atom undefined_serial (in case no
172                  messages has been sent).
173
174                min_trans_id:
175                  First trans id.
176
177                  A positive integer, defaults to 1.
178
179                max_trans_id:
180                  Last trans id.
181
182                  A positive integer or infinity, defaults to infinity.
183
184                request_timer:
185                  Wait for reply.
186
187                  The timer is cancelled when a reply is received.
188
189                  When a pending message is received, the timer  is  cancelled
190                  and  the  long_request_timer is started instead (see below).
191                  No resends will be performed from this point (since  we  now
192                  know that the other side has received the request).
193
194                  When  the  timer reaches an intermediate expire, the request
195                  is resent and the timer is restarted.
196
197                  When the timer reaches the final expire, either the function
198                  megaco:call  will  return with {error, timeout} or the call‐
199                  back function handle_trans_reply will be called with UserRe‐
200                  ply = {error, timeout} (if megaco:cast was used).
201
202                  A   Megaco   Timer  (see  explanation  above),  defaults  to
203                  #megaco_incr_timer{}.
204
205                long_request_timer:
206                  Wait for reply after having received a pending message.
207
208                  When the timer reaches an intermediate expire, the timer  is
209                  restarted.
210
211                  When  a  pending  message  is  received,  and  the  long_re‐
212                  quest_timer is not "on its final leg",  the  timer  will  be
213                  restarted,  and,  if long_request_resend = true, the request
214                  will be re-sent.
215
216                  A Megaco Timer (see explanation above), defaults to 60  sec‐
217                  onds.
218
219                long_request_resend:
220                  This  option  indicates weather the request should be resent
221                  until the reply is received, even though a  pending  message
222                  has been received.
223
224                  Normally, after a pending message has been received, the re‐
225                  quest is not resent (since a pending message is  an  indica‐
226                  tion  that the request has been received). But since the re‐
227                  ply (to the request) can be lost,  this  behaviour  has  its
228                  values.
229
230                  It  is  of course pointless to set this value to true unless
231                  the long_request_timer (see above) is also set to an  incre‐
232                  mental timer (#megaco_incr_timer{}).
233
234                  A boolean, defaults to false.
235
236                reply_timer:
237                  Wait for an ack.
238
239                  When  a  request is received, some info related to the reply
240                  is store internally (e.g. the binary  of  the  reply).  This
241                  info will live until either an ack is received or this timer
242                  expires. For instance, if the same request is received again
243                  (e.g.  a request with the same transaction id), the (stored)
244                  reply will be (re-) sent automatically by megaco.
245
246                  If the timer is of type #megaco_incr_timer{}, then for  each
247                  intermediate timout, the reply will be resent (this is valid
248                  until the ack is received or the timer expires).
249
250                  A Megaco Timer (see explanation above), defaults to 30000.
251
252                request_keep_alive_timeout:
253                  Specifies the timeout time for the request-keep-alive timer.
254
255                  This timer is started when the first reply to  an  asynchro‐
256                  nous  request  (issued using the megaco:cast/3 function) ar‐
257                  rives. As long as this timer is running, replies will be de‐
258                  livered  via  the  handle_trans_reply/4,5 callback function,
259                  with their "arrival  number"  (see  UserReply  of  the  han‐
260                  dle_trans_reply/4,5 callback function).
261
262                  Replies arriving after the timer has expired, will be deliv‐
263                  ered using the  handle_unexpected_trans/3,4  callback  func‐
264                  tion.
265
266                  The  timeout  time can have the values: plain | integer() >=
267                  0.
268
269                  Defaults to plain.
270
271                call_proxy_gc_timeout:
272                  Timeout time for the call proxy.
273
274                  When a request is sent using the call/3  function,  a  proxy
275                  process is started to handle all replies. When the reply has
276                  been received and delivered to the user, the  proxy  process
277                  continue  to exist for as long as this option specifies. Any
278                  received messages, is passed on to the  user  via  the  han‐
279                  dle_unexpected_trans callback function.
280
281                  The  timeout  time  is  in milliseconds. A value of 0 (zero)
282                  means that the proxy process will exit  directly  after  the
283                  reply has been delivered.
284
285                  An integer >= 0, defaults to 5000 (= 5 seconds).
286
287                auto_ack:
288                  Automatic  send  transaction  ack when the transaction reply
289                  has been received (see trans_ack below).
290
291                  This is used for three-way-handshake.
292
293                  A boolean, defaults to false.
294
295                trans_ack:
296                  Shall ack's be accumulated or not.
297
298                  This property is only valid if auto_ack is true.
299
300                  If auto_ack is true, then if trans_ack is false, ack's  will
301                  be  sent  immediately. If trans_ack is true, then ack's will
302                  instead be sent to the transaction sender process for  accu‐
303                  mulation   and   later   sending   (see  trans_ack_maxcount,
304                  trans_req_maxcount,  trans_req_maxsize,   trans_ack_maxcount
305                  and trans_timer).
306
307                  See also transaction sender for more info.
308
309                  An boolean, defaults to false.
310
311                trans_ack_maxcount:
312                  Maximum number of accumulated ack's. At most this many ack's
313                  will be accumulated by the transaction  sender  (if  started
314                  and configured to accumulate ack's).
315
316                  See also transaction sender for more info.
317
318                  An integer, defaults to 10.
319
320                trans_req:
321                  Shall requests be accumulated or not.
322
323                  If  trans_req is false, then request(s) will be sent immedi‐
324                  ately (in its own message).
325
326                  If trans_req is true, then request(s) will instead  be  sent
327                  to the transaction sender process for accumulation and later
328                  sending   (see    trans_ack_maxcount,    trans_req_maxcount,
329                  trans_req_maxsize, trans_ack_maxcount and trans_timer).
330
331                  See also transaction sender for more info.
332
333                  An boolean, defaults to false.
334
335                trans_req_maxcount:
336                  Maximum  number  of  accumulated requests. At most this many
337                  requests will be accumulated by the transaction  sender  (if
338                  started and configured to accumulate requests).
339
340                  See also transaction sender for more info.
341
342                  An integer, defaults to 10.
343
344                trans_req_maxsize:
345                  Maximum  size of the accumulated requests. At most this much
346                  requests will be accumulated by the transaction  sender  (if
347                  started and configured to accumulate requests).
348
349                  See also transaction sender for more info.
350
351                  An integer, defaults to 2048.
352
353                trans_timer:
354                  Transaction  sender  timeout time. Has two functions. First,
355                  if the value is 0, then transactions will not be accumulated
356                  (e.g.  the  transaction sender process will not be started).
357                  Second, if the value is greater  then  0  and  auto_ack  and
358                  trans_ack are both true or if trans_req is true, then trans‐
359                  action sender will be started and transactions (which is de‐
360                  pending  on the values of auto_ack, trans_ack and trans_req)
361                  will be accumulated, for later sending.
362
363                  See also transaction sender for more info.
364
365                  An integer, defaults to 0.
366
367                pending_timer:
368                  Automatically send pending if the  timer  expires  before  a
369                  transaction  reply  has been sent. This timer is also called
370                  provisional response timer.
371
372                  A Megaco Timer (see explanation above), defaults to 30000.
373
374                sent_pending_limit:
375                  Sent pending limit (see the MGOriginatedPendingLimit and the
376                  MGCOriginatedPendingLimit  of the megaco root package). This
377                  parameter specifies how many pending messages  that  can  be
378                  sent  (for  a  given received transaction request). When the
379                  limit is exceeded, the  transaction  is  aborted  (see  han‐
380                  dle_trans_request_abort) and an error message is sent to the
381                  other side.
382
383                  Note that this has no effect on the actual sending of  pend‐
384                  ing transactions. This is either implicit (e.g. when receiv‐
385                  ing a re-sent transaction request for a request which is be‐
386                  ing  processed)  or  controlled  by  the  pending_timer, see
387                  above.
388
389                  A positive integer or infinity, defaults to infinity.
390
391                recv_pending_limit:
392                  Receive pending limit (see the MGOriginatedPendingLimit  and
393                  the  MGCOriginatedPendingLimit  of the megaco root package).
394                  This parameter specifies how many pending messages that  can
395                  be received (for a sent transaction request). When the limit
396                  is exceeded, the transaction is considered lost, and an  er‐
397                  ror  returned  to  the  user (through the call-back function
398                  handle_trans_reply).
399
400                  A positive integer or infinity, defaults to infinity.
401
402                send_mod:
403                  Send callback module which exports send_message/2. The func‐
404                  tion  SendMod:send_message(SendHandle,  Binary)  is  invoked
405                  when the bytes needs to be transmitted to the remote user.
406
407                  An atom, defaults to megaco_tcp.
408
409                encoding_mod:
410                  Encoding callback module which exports encode_message/2  and
411                  decode_message/2.   The   function   EncodingMod:encode_mes‐
412                  sage(EncodingConfig, MegacoMessage) is  invoked  whenever  a
413                  'MegacoMessage' record needs to be translated into an Erlang
414                  binary. The function EncodingMod:decode_message(EncodingCon‐
415                  fig,  Binary)  is invoked whenever an Erlang binary needs to
416                  be translated into a 'MegacoMessage' record.
417
418                  An atom, defaults to megaco_pretty_text_encoder.
419
420                encoding_config:
421                  Encoding module config.
422
423                  A list, defaults to [].
424
425                protocol_version:
426                  Actual protocol version.
427
428                  An integer, default is 1.
429
430                strict_version:
431                  Strict version control, i.e. when  a  message  is  received,
432                  verify that the version is that which was negotiated.
433
434                  An boolean, default is true.
435
436                reply_data:
437                  Default reply data.
438
439                  Any term, defaults to the atom undefined.
440
441                user_mod:
442                  Name of the user callback module. See the the reference man‐
443                  ual for megaco_user for more info.
444
445                user_args:
446                  List of extra arguments to the user callback functions.  See
447                  the the reference manual for megaco_user for more info.
448
449                threaded:
450                  If a received message contains several transaction requests,
451                  this option indicates whether the requests should be handled
452                  sequentially in the same process (false), or if each request
453                  should be handled by its own process (true i.e.  a  separate
454                  process is spawned for each request).
455
456                  An boolean, defaults to false.
457
458                resend_indication:
459                  This option indicates weather the transport module should be
460                  told if a message send is a resend or not.
461
462                  If false, megaco messages are sent  using  the  send_message
463                  function.
464
465                  If  true,  megaco  message  re-sends  are made using the re‐
466                  send_message function. The initial  message  send  is  still
467                  done using the send_message function.
468
469                  The  special  value flag instead indicates that the function
470                  send_message/3 shall be used.
471
472                  A resend_indication(), defaults to false.
473
474                segment_reply_ind:
475                  This option specifies if the user shall be notified  of  re‐
476                  ceived segment replies or not.
477
478                  See handle_segment_reply callback function for more informa‐
479                  tion.
480
481                  A boolean, defaults to false.
482
483                segment_recv_timer:
484                  This timer is started when the segment indicated by the seg‐
485                  mentation  complete  token is received, but all segments has
486                  not yet been received.
487
488                  When the timer finally expires, a "megaco segments  not  re‐
489                  ceived"  (459)  error  message is sent to the other side and
490                  the user is notified with a segment timeout UserReply in ei‐
491                  ther  the handle_trans_reply callback function or the return
492                  value of the call function.
493
494                  A Megaco Timer (see explanation above), defaults to 10000.
495
496                segment_send:
497                  Shall outgoing messages be segmented or not:
498
499                  none:
500                    Do not segment outgoing reply  messages.  This  is  useful
501                    when  either  it is known that messages are never to large
502                    or that the transport protocol can handle such  things  on
503                    its own (e.g. TCP or SCTP).
504
505                  integer() > 0:
506                    Outgoing  reply  messages will be segmented as needed (see
507                    max_pdu_size below). This value, K, indicate the outstand‐
508                    ing window, i.e. how many segments can be outstanding (not
509                    acknowledged) at any given time.
510
511                  infinity:
512                    Outgoing reply messages will be segmented as  needed  (see
513                    max_pdu_size below). Segment messages are sent all at once
514                    (i.e. no acknowledgement awaited before sending  the  next
515                    segment).
516
517                  Defaults to none.
518
519                max_pdu_size:
520                  Max  message size. If the encoded message (PDU) exceeds this
521                  size, the message should be segmented, and then encoded.
522
523                  A positive integer or infinity, defaults to infinity.
524
525       update_user_info(UserMid, Item, Value) -> ok | {error, Reason}
526
527              Types:
528
529                 UserMid = megaco_mid()
530                 Item = user_info_item()
531                 Value = user_info_value()
532                 Reason = term()
533
534              Update information about a user
535
536              Requires that the user is started. See megaco:user_info/2  about
537              which items and values that are valid.
538
539       conn_info(ConnHandle) -> [{Item, Value}]
540       conn_info(ConnHandle, Item) -> Value | exit(Reason)
541
542              Types:
543
544                 ConnHandle = #megaco_conn_handle{}
545                 Item = conn_info_item()
546                 Value = conn_info_value()
547                 Reason = {no_such_connection, ConnHandle} | term()
548
549              Lookup information about an active connection
550
551              Requires that the connection is active.
552
553                control_pid:
554                  The process identifier of the controlling process for a con‐
555                  nection.
556
557                send_handle:
558                  Opaque send handle whose contents is internal for  the  send
559                  module. May be any term.
560
561                local_mid:
562                  The  local  mid  (of  the  connection,  i.e.  the  own mid).
563                  megaco_mid().
564
565                remote_mid:
566                  The remote mid (of the connection). megaco_mid().
567
568                receive_handle:
569                  Construct a megaco_receive_handle record.
570
571                trans_id:
572                  Next transaction id. A positive integer or  the  atom  unde‐
573                  fined_serial (only in case of error).
574
575                  Note  that  transaction id's are (currently) maintained on a
576                  per user basis so there is no way to be sure that the  value
577                  returned  will  actually  be  used for a transaction sent on
578                  this connection (in case a  user  has  several  connections,
579                  which is not at all unlikely).
580
581                max_trans_id:
582                  Last trans id.
583
584                  A positive integer or infinity, defaults to infinity.
585
586                request_timer:
587                  Wait for reply.
588
589                  The timer is cancelled when a reply is received.
590
591                  When  a  pending message is received, the timer is cancelled
592                  and the long_request_timer is started instead  (see  below).
593                  No  resends  will be performed from this point (since we now
594                  know that the other side has received the request).
595
596                  When the timer reaches an intermediate expire,  the  request
597                  is resent and the timer is restarted.
598
599                  When the timer reaches the final expire, either the function
600                  megaco:call will return with {error, timeout} or  the  call‐
601                  back function handle_trans_reply will be called with UserRe‐
602                  ply = {error, timeout} (if megaco:cast was used).
603
604                  A  Megaco  Timer  (see  explanation  above),   defaults   to
605                  #megaco_incr_timer{}.
606
607                long_request_timer:
608                  Wait for reply after having received a pending message.
609
610                  When  the  timer  reaches  an intermediate expire, the timer
611                  restarted.
612
613                  When  a  pending  message  is  received,  and  the  long_re‐
614                  quest_timer  is  not  "on  its final leg", the timer will be
615                  restarted, and, if long_request_resend = true,  the  request
616                  will be re-sent.
617
618                  A  Megaco Timer (see explanation above), defaults to 60 sec‐
619                  onds.
620
621                request_keep_alive_timeout:
622                  Specifies the timeout time for the request-keep-alive timer.
623
624                  This timer is started when the first reply to  an  asynchro‐
625                  nous  request  (issued using the megaco:cast/3 function) ar‐
626                  rives. As long as this timer is running, replies will be de‐
627                  livered  via  the  handle_trans_reply/4,5 callback function,
628                  with their "arrival  number"  (see  UserReply  of  the  han‐
629                  dle_trans_reply/4,5 callback function).
630
631                  Replies arriving after the timer has expired, will be deliv‐
632                  ered using the  handle_unexpected_trans/3,4  callback  func‐
633                  tion.
634
635                  The  timeout  time can have the values: plain | integer() >=
636                  0.
637
638                  Defaults to plain.
639
640                long_request_resend:
641                  This option indicates weather the request should  be  resent
642                  until  the  reply is received, even though a pending message
643                  has been received.
644
645                  Normally, after a pending message has been received, the re‐
646                  quest  is  not resent (since a pending message is an indica‐
647                  tion that the request has been received). But since the  re‐
648                  ply  (to  the  request)  can be lost, this behaviour has its
649                  values.
650
651                  It is of course pointless to set this value to  true  unless
652                  the  long_request_timer (see above) is also set to an incre‐
653                  mental timer (#megaco_incr_timer{}).
654
655                  A boolean, defaults to false.
656
657                reply_timer:
658                  Wait for an ack.
659
660                  When a request is received, some info related to  the  reply
661                  is  store  internally  (e.g.  the binary of the reply). This
662                  info will live until either an ack is received or this timer
663                  expires. For instance, if the same request is received again
664                  (e.g. a request with the same transaction id), the  (stored)
665                  reply will be (re-) sent automatically by megaco.
666
667                  If  the timer is of type #megaco_incr_timer{}, then for each
668                  intermediate timout, the reply will be resent (this is valid
669                  until the ack is received or the timer expires).
670
671                  A Megaco Timer (see explanation above), defaults to 30000.
672
673                call_proxy_gc_timeout:
674                  Timeout time for the call proxy.
675
676                  When  a  request  is sent using the call/3 function, a proxy
677                  process is started to handle all replies. When the reply has
678                  been  received  and delivered to the user, the proxy process
679                  continue to exist for as long as this option specifies.  Any
680                  received  messages,  is  passed  on to the user via the han‐
681                  dle_unexpected_trans callback function.
682
683                  The timeout time is in milliseconds. A  value  of  0  (zero)
684                  means  that  the  proxy process will exit directly after the
685                  reply has been delivered.
686
687                  An integer >= 0, defaults to 5000 (= 5 seconds).
688
689                auto_ack:
690                  Automatic send transaction ack when  the  transaction  reply
691                  has been received (see trans_ack below).
692
693                  This is used for three-way-handshake.
694
695                  A boolean, defaults to false.
696
697                trans_ack:
698                  Shall ack's be accumulated or not.
699
700                  This property is only valid if auto_ack is true.
701
702                  If  auto_ack is true, then if trans_ack is false, ack's will
703                  be sent immediately. If trans_ack is true, then  ack's  will
704                  instead  be sent to the transaction sender process for accu‐
705                  mulation  and   later   sending   (see   trans_ack_maxcount,
706                  trans_req_maxcount,   trans_req_maxsize,  trans_ack_maxcount
707                  and trans_timer).
708
709                  See also transaction sender for more info.
710
711                  An boolean, defaults to false.
712
713                trans_ack_maxcount:
714                  Maximum number of accumulated ack's. At most this many ack's
715                  will  be  accumulated  by the transaction sender (if started
716                  and configured to accumulate ack's).
717
718                  See also transaction sender for more info.
719
720                  An integer, defaults to 10.
721
722                trans_req:
723                  Shall requests be accumulated or not.
724
725                  If trans_req is false, then request(s) will be sent  immedi‐
726                  ately (in its own message).
727
728                  If  trans_req  is true, then request(s) will instead be sent
729                  to the transaction sender process for accumulation and later
730                  sending    (see    trans_ack_maxcount,   trans_req_maxcount,
731                  trans_req_maxsize, trans_ack_maxcount and trans_timer).
732
733                  See also transaction sender for more info.
734
735                  An boolean, defaults to false.
736
737                trans_req_maxcount:
738                  Maximum number of accumulated requests. At  most  this  many
739                  requests  will  be accumulated by the transaction sender (if
740                  started and configured to accumulate requests).
741
742                  See also transaction sender for more info.
743
744                  An integer, defaults to 10.
745
746                trans_req_maxsize:
747                  Maximum size of the accumulated requests. At most this  much
748                  requests  will  be accumulated by the transaction sender (if
749                  started and configured to accumulate requests).
750
751                  See also transaction sender for more info.
752
753                  An integer, defaults to 2048.
754
755                trans_timer:
756                  Transaction sender timeout time. Has two  functions.  First,
757                  if the value is 0, then transactions will not be accumulated
758                  (e.g. the transaction sender process will not  be  started).
759                  Second,  if  the  value  is  greater then 0 and auto_ack and
760                  trans_ack is true or if trans_req is true, then  transaction
761                  sender  will be started and transactions (which is depending
762                  on the values of auto_ack, trans_ack and trans_req) will  be
763                  accumulated, for later sending.
764
765                  See also transaction sender for more info.
766
767                  An integer, defaults to 0.
768
769                pending_timer:
770                  Automatic  send transaction pending if the timer expires be‐
771                  fore a transaction reply has been sent. This timer  is  also
772                  called provisional response timer.
773
774                  A Megaco Timer (see explanation above), defaults to 30000.
775
776                sent_pending_limit:
777                  Sent pending limit (see the MGOriginatedPendingLimit and the
778                  MGCOriginatedPendingLimit of the megaco root package).  This
779                  parameter  specifies  how  many pending messages that can be
780                  sent (for a given received transaction  request).  When  the
781                  limit  is  exceeded,  the  transaction  is aborted (see han‐
782                  dle_trans_request_abort) and an error message is sent to the
783                  other side.
784
785                  Note  that this has no effect on the actual sending of pend‐
786                  ing transactions. This is either implicit (e.g. when receiv‐
787                  ing a re-sent transaction request for a request which is be‐
788                  ing processed)  or  controlled  by  the  pending_timer,  see
789                  above.
790
791                  A positive integer or infinity, defaults to infinity.
792
793                recv_pending_limit:
794                  Receive  pending limit (see the MGOriginatedPendingLimit and
795                  the MGCOriginatedPendingLimit of the megaco  root  package).
796                  This  parameter specifies how many pending messages that can
797                  be received (for a sent transaction request). When the limit
798                  is  exceeded, the transaction is considered lost, and an er‐
799                  ror returned to the user  (through  the  call-back  function
800                  handle_trans_reply).
801
802                  A positive integer or infinity, defaults to infinity.
803
804                send_mod:
805                  Send callback module which exports send_message/2. The func‐
806                  tion  SendMod:send_message(SendHandle,  Binary)  is  invoked
807                  when the bytes needs to be transmitted to the remote user.
808
809                  An atom, defaults to megaco_tcp.
810
811                encoding_mod:
812                  Encoding  callback module which exports encode_message/2 and
813                  decode_message/2.   The   function   EncodingMod:encode_mes‐
814                  sage(EncodingConfig,  MegacoMessage)  is  invoked whenever a
815                  'MegacoMessage' record needs to be translated into an Erlang
816                  binary. The function EncodingMod:decode_message(EncodingCon‐
817                  fig, Binary) is invoked whenever an Erlang binary  needs  to
818                  be translated into a 'MegacoMessage' record.
819
820                  An atom, defaults to megaco_pretty_text_encoder.
821
822                encoding_config:
823                  Encoding module config.
824
825                  A list, defaults to [].
826
827                protocol_version:
828                  Actual protocol version.
829
830                  An positive integer, Current default is 1.
831
832                strict_version:
833                  Strict  version  control,  i.e.  when a message is received,
834                  verify that the version is that which was negotiated.
835
836                  An boolean, default is true.
837
838                reply_data:
839                  Default reply data.
840
841                  Any term, defaults to the atom undefined.
842
843                threaded:
844                  If a received message contains several transaction requests,
845                  this option indicates whether the requests should be handled
846                  sequentially in the same process (false), or if each request
847                  should  be  handled by its own process (true i.e. a separate
848                  process is spawned for each request).
849
850                  An boolean, defaults to false.
851
852                resend_indication:
853                  This option indicates weather the transport module should be
854                  told if a message send is a resend or not.
855
856                  If  false, megaco messages are sent using the send_message/2
857                  function.
858
859                  If true, megaco message re-sends  are  made  using  the  re‐
860                  send_message  function.  The  initial  message send is still
861                  done using the send_message function.
862
863                  The special value flag instead indicates that  the  function
864                  send_message/3 shall be used.
865
866                  A resend_indication(), defaults to false.
867
868                segment_reply_ind:
869                  This  option  specifies if the user shall be notified of re‐
870                  ceived segment replies or not.
871
872                  See handle_segment_reply callback function for more informa‐
873                  tion.
874
875                  A boolean, defaults to false.
876
877                segment_recv_timer:
878                  This timer is started when the segment indicated by the seg‐
879                  mentation complete token (e.g. the last of the segment which
880                  makes  up  the  reply) is received, but all segments has not
881                  yet been received.
882
883                  When the timer finally expires, a "megaco segments  not  re‐
884                  ceived"  (459)  error  message is sent to the other side and
885                  the user is notified with a segment timeout UserReply in ei‐
886                  ther  the handle_trans_reply callback function or the return
887                  value of the call function.
888
889                  A Megaco Timer (see explanation above), defaults to 10000.
890
891                segment_send:
892                  Shall outgoing messages be segmented or not:
893
894                  none:
895                    Do not segment outgoing reply  messages.  This  is  useful
896                    when  either  it is known that messages are never to large
897                    or that the transport protocol can handle such  things  on
898                    its own (e.g. TCP or SCTP).
899
900                  integer() > 0:
901                    Outgoing  reply  messages will be segmented as needed (see
902                    max_pdu_size below). This value, K, indicate the outstand‐
903                    ing window, i.e. how many segments can be outstanding (not
904                    acknowledged) at any given time.
905
906                  infinity:
907                    Outgoing reply messages will be segmented as  needed  (see
908                    max_pdu_size below). Segment messages are sent all at once
909                    (i.e. no acknowledgement awaited before sending  the  next
910                    segment).
911
912                  Defaults to none.
913
914                max_pdu_size:
915                  Max  message size. If the encoded message (PDU) exceeds this
916                  size, the message should be segmented, and then encoded.
917
918                  A positive integer or infinity, defaults to infinity.
919
920       update_conn_info(ConnHandle, Item, Value) -> ok | {error, Reason}
921
922              Types:
923
924                 ConnHandle = #megaco_conn_handle{}
925                 Item = conn_info_item()
926                 Value = conn_info_value()
927                 Reason = term()
928
929              Update information about an active connection
930
931              Requires    that    the    connection    is    activated.    See
932              megaco:conn_info/2 about which items and values that are valid.
933
934       system_info() -> [{Item, Value}] | exit(Reason)
935       system_info(Item) -> Value | exit(Reason)
936
937              Types:
938
939                 Item = system_info_item()
940
941              Lookup system information
942
943              The following items are valid:
944
945                text_config:
946                  The text encoding config.
947
948                connections:
949                  Lists   all   active   connections.   Returns   a   list  of
950                  megaco_conn_handle records.
951
952                users:
953                  Lists all active users. Returns a list of megaco_mid()'s.
954
955                n_active_requests:
956                  Returns an integer representing the number of requests  that
957                  has  originated  from  this Erlang node and still are active
958                  (and therefore consumes system resources).
959
960                n_active_replies:
961                  Returns an integer representing the number of  replies  that
962                  has  originated  from  this Erlang node and still are active
963                  (and therefore consumes system resources).
964
965                n_active_connections:
966                  Returns an integer representing the number of active connec‐
967                  tions.
968
969       info() -> Info
970
971              Types:
972
973                 Info = [{Key, Value}]
974
975              This  function  produces  a list of information about the megaco
976              application. Such as users and  their  config,  connections  and
977              their config, statistics and so on.
978
979              This  information  can  be  produced by the functions user_info,
980              conn_info, system_info and get_stats but this is a simple way to
981              get it all at once.
982
983       connect(ReceiveHandle,   RemoteMid,  SendHandle,  ControlPid)  ->  {ok,
984       ConnHandle} | {error, Reason}
985       connect(ReceiveHandle, RemoteMid,  SendHandle,  ControlPid,  Extra)  ->
986       {ok, ConnHandle} | {error, Reason}
987
988              Types:
989
990                 ReceiveHandle = #megaco_receive_handle{}
991                 RemoteMid = preliminary_mid | megaco_mid()
992                 SendHandle = term()
993                 ControlPid = pid()
994                 ConnHandle = #megaco_conn_handle{}
995                 Reason = connect_reason() | handle_connect_reason() | term()
996                 connect_reason()  =  {no_such_user, LocalMid} | {already_con‐
997                 nected, ConnHandle} | term()
998                 handle_connect_error() = {connection_refused,  ConnData,  Er‐
999                 rorInfo} | term()
1000                 LocalMid = megaco_mid()
1001                 ConnData = term()
1002                 ErrorInfo = term()
1003                 Extra = term()
1004
1005              Establish a "virtual" connection
1006
1007              Activates  a  connection to a remote user. When this is done the
1008              connection can be used to send messages (with  SendMod:send_mes‐
1009              sage/2). The ControlPid is the identifier of a process that con‐
1010              trols the connection. That process will be supervised and if  it
1011              dies,  this will be detected and the UserMod:handle_disconnect/2
1012              callback function will be invoked. See  the  megaco_user  module
1013              for  more  info about the callback arguments. The connection may
1014              also explicitly be deactivated by invoking megaco:disconnect/2.
1015
1016              The ControlPid may be the identity of a process residing on  an‐
1017              other  Erlang node. This is useful when you want to distribute a
1018              user over several Erlang nodes. In such a case one of the  nodes
1019              has  the physical connection. When a user residing on one of the
1020              other nodes needs to  send  a  request  (with  megaco:call/3  or
1021              megaco:cast/3),  the message will encoded on the originating Er‐
1022              lang node, and then be forwarded to the node with  the  physical
1023              connection. When the reply arrives, it will be forwarded back to
1024              the originator. The distributed connection may explicitly be de‐
1025              activated  by  a local call to megaco:disconnect/2 or implicitly
1026              when the physical connection is deactivated (with megaco:discon‐
1027              nect/2, killing the controlling process, halting the other node,
1028              ...).
1029
1030              The call of this function will  trigger  the  callback  function
1031              UserMod:handle_connect/2 to be invoked. See the megaco_user mod‐
1032              ule for more info about the callback arguments.
1033
1034              A connection may be established in several ways:
1035
1036                provisioned MID:
1037                  The MG may explicitly invoke megaco:connect/4 and use a pro‐
1038                  visioned MID of the MGC as the RemoteMid.
1039
1040                upgrade preliminary MID:
1041                  The  MG may explicitly invoke megaco:connect/4 with the atom
1042                  'preliminary_mid' as a temporary MID of the MGC, send an in‐
1043                  tial  message,  the  Service  Change Request, to the MGC and
1044                  then wait for an initial message, the Service Change  Reply.
1045                  When the reply arrives, the Megaco application will pick the
1046                  MID of the MGC from the message header and automatically up‐
1047                  grade  the  connection to be a "normal" connection. By using
1048                  this method of establishing  the  connection,  the  callback
1049                  function UserMod:handle_connect/2 to be invoked twice. First
1050                  with a ConnHandle with the remote_mid-field set to  prelimi‐
1051                  nary_mid,  and then when the connection upgrade is done with
1052                  the remote_mid-field set to the actual MID of the MGC.
1053
1054                automatic:
1055                  When the MGC receives its first message, the Service  Change
1056                  Request, the Megaco application will automatically establish
1057                  the connection by using the MG  MID  found  in  the  message
1058                  header as remote mid.
1059
1060                distributed:
1061                  When  a  user (MG/MGC) is distributed over several nodes, it
1062                  is required that the node hosting the connection already has
1063                  activated  the  connection  and  that  it is in the "normal"
1064                  state. The RemoteMid must be a real Megaco  MID  and  not  a
1065                  preliminary_mid.
1066
1067              An  initial  megaco_receive_handle  record  may be obtained with
1068              megaco:user_info(UserMid, receive_handle)
1069
1070              The send handle is provided by the preferred  transport  module,
1071              e.g.  megaco_tcp,  megaco_udp. Read the documentation about each
1072              transport module about the details.
1073
1074              The connect is done in two steps: first an  internal  connection
1075              setup and then by calling the user handle_connect callback func‐
1076              tion. The first step could result in an error with Reason = con‐
1077              nect_reason()  and the second an error with Reason = handle_con‐
1078              nect_reason():
1079
1080                connect_reason():
1081                  An error with this reason is generated by the megaco  appli‐
1082                  cation itself.
1083
1084                handle_connect_reason():
1085                  An  error with this reason is caused by the user handle_con‐
1086                  nect callback function either returning an error or  an  in‐
1087                  valid value.
1088
1089              Extra  can  be  any  term()  except the atom ignore_extra. It is
1090              passed (back) to the user via the callback function  handle_con‐
1091              nect/3.
1092
1093       disconnect(ConnHandle, DiscoReason) -> ok | {error, ErrReason}
1094
1095              Types:
1096
1097                 ConnHandle = conn_handle()
1098                 DiscoReason = term()
1099                 ErrReason = term()
1100
1101              Tear down a "virtual" connection
1102
1103              Causes  the  UserMod:handle_disconnect/2 callback function to be
1104              invoked. See the megaco_user module  for  more  info  about  the
1105              callback arguments.
1106
1107       call(ConnHandle, Actions, Options) -> {ProtocolVersion, UserReply}
1108
1109              Types:
1110
1111                 ConnHandle = conn_handle()
1112                 Actions = action_reqs() | [action_reqs()]
1113                 action_reqs() = binary() | [action_request()]
1114                 Options = [send_option()]
1115                 send_option()  =  {request_timer, megaco_timer()} | {long_re‐
1116                 quest_timer, megaco_timer()} | {send_handle, term()} |  {pro‐
1117                 tocol_version,     integer()}    |    {call_proxy_gc_timeout,
1118                 call_proxy_gc_timeout()}
1119                 ProtocolVersion = integer()
1120                 UserReply = user_reply() | [user_reply()]
1121                 user_reply() = success() | failure()
1122                 success() = {ok, result()} | {ok, result(), extra()}
1123                 result() = message_result() | segment_result()
1124                 message_result() = action_reps()
1125                 segment_result() = segments_ok()
1126                 failure() = {error, reason()} | {error, reason(), extra()}
1127                 reason() = message_reason() |  segment_reason()  |  user_can‐
1128                 cel_reason() | send_reason() | other_reason()
1129                 message_reason() = error_desc()
1130                 segment_reason() = {segment, segments_ok(), segments_err()} |
1131                 {segment_timeout,  missing_segments(),  segments_ok(),   seg‐
1132                 ments_err()}
1133                 segments_ok() = [segment_ok()]
1134                 segment_ok() = {segment_no(), action_reps()}
1135                 segments_err() = [segment_err()]
1136                 segment_err() = {segment_no(), error_desc()}
1137                 missing_segments() = [segment_no()]
1138                 user_cancel_reason()   =  {user_cancel,  reason_for_user_can‐
1139                 cel()}
1140                 reason_for_user_cancel() = term()
1141                 send_reason() =  send_cancelled_reason()  |  send_failed_rea‐
1142                 son()
1143                 send_cancelled_reason()   =   {send_message_cancelled,   rea‐
1144                 son_for_send_cancel()}
1145                 reason_for_send_cancel() = term()
1146                 send_failed_reason()     =     {send_message_failed,     rea‐
1147                 son_for_send_failure()}
1148                 reason_for_send_failure() = term()
1149                 other_reason() = {wrong_mid, WrongMid, RightMid, TR} | term()
1150                 WrongMid = mid()
1151                 RightMid = mid()
1152                 TR = transaction_reply()
1153                 action_reps() = [action_reply()]
1154                 call_proxy_gc_timeout() = integer() >= 0
1155                 extra() = term()
1156
1157              Sends  one  or more transaction request(s) and waits for the re‐
1158              ply.
1159
1160              When sending one transaction in a message, Actions should be ac‐
1161              tion_reqs()  (UserReply will then be user_reply()). When sending
1162              several transactions  in  a  message,  Actions  should  be  [ac‐
1163              tion_reqs()]  (UserReply will then be [user_reply()]). Each ele‐
1164              ment of the list is part of one transaction.
1165
1166              For some of our codecs (not binary), it is also possible to pre-
1167              encode  the  actions, in which case Actions will be either a bi‐
1168              nary() or [binary()].
1169
1170              The function returns when the reply arrives,  when  the  request
1171              timer  eventually times out or when the outstanding requests are
1172              explicitly cancelled.
1173
1174              The  default  values  of  the  send  options  are  obtained   by
1175              megaco:conn_info(ConnHandle,  Item). But the send options above,
1176              may explicitly be overridden.
1177
1178              The ProtocolVersion version is the version actually  encoded  in
1179              the reply message.
1180
1181              At  success(),  the  UserReply  contains a list of 'ActionReply'
1182              records possibly containing error indications.
1183
1184              A message_error(), indicates that the remote  user  has  replied
1185              with an explicit transactionError.
1186
1187              A  user_cancel_error(), indicates that the request has been can‐
1188              celed by the user. reason_for_user_cancel() is the reason  given
1189              in the call to the cancel function.
1190
1191              A  send_error(),  indicates that the send function of the megaco
1192              transport callback module failed to send the request. There  are
1193              two separate cases: send_cancelled_reason() and send_failed_rea‐
1194              son(). The first is the result of the  send  function  returning
1195              {cancel,  Reason} and the second is some other kind of erroneous
1196              return value. See the send_message function for more info.
1197
1198              An other_error(), indicates some other error such as timeout.
1199
1200              For more info about the extra() part of the result, see the note
1201              in the user callback module documentation.
1202
1203       cast(ConnHandle, Actions, Options) -> ok | {error, Reason}
1204
1205              Types:
1206
1207                 ConnHandle = conn_handle()
1208                 Actions = action_reqs() | [action_reqs()]
1209                 action_reqs() = binary() | [action_request()]
1210                 Options = [send_option()]
1211                 send_option()      =     {request_keep_alive_timeout,     re‐
1212                 quest_keep_alive_timeout()} | {request_timer, megaco_timer()}
1213                 |   {long_request_timer,   megaco_timer()}   |  {send_handle,
1214                 term()} | {reply_data, reply_data()} | {protocol_version, in‐
1215                 teger()}
1216                 request_keep_alive_timeout() = plain | integer() >= 0
1217                 Reason = term()
1218
1219              Sends one or more transaction request(s) but does NOT wait for a
1220              reply
1221
1222              When sending one transaction in a message, Actions should be ac‐
1223              tion_reqs(). When sending several transactions in a message, Ac‐
1224              tions should be [action_reqs()]. Each element  of  the  list  is
1225              part of one transaction.
1226
1227              For some of our codecs (not binary), it is also possible to pre-
1228              encode the actions, in which case Actions will be either  a  bi‐
1229              nary() or [binary()].
1230
1231              The   default  values  of  the  send  options  are  obtained  by
1232              megaco:conn_info(ConnHandle, Item). But the send options  above,
1233              may explicitly be overridden.
1234
1235              The  ProtocolVersion  version is the version actually encoded in
1236              the reply message.
1237
1238              The callback function  UserMod:handle_trans_reply/4  is  invoked
1239              when  the reply arrives, when the request timer eventually times
1240              out or when the outstanding requests are  explicitly  cancelled.
1241              See  the megaco_user module for more info about the callback ar‐
1242              guments.
1243
1244              Given as UserData argument to UserMod:handle_trans_reply/4.
1245
1246       encode_actions(ConnHandle, Actions, Options) -> {ok, BinOrBins} |  {er‐
1247       ror, Reason}
1248
1249              Types:
1250
1251                 ConnHandle = conn_handle()
1252                 Actions = action_reqs() | [action_reqs()]
1253                 action_reqs() = [#'ActionRequest'{}]
1254                 Options = [send_option()]
1255                 send_option()  =  {request_timer, megaco_timer()} | {long_re‐
1256                 quest_timer, megaco_timer()} | {send_handle, term()} |  {pro‐
1257                 tocol_version, integer()}
1258                 BinOrBins = binary() | [binary()]
1259                 Reason = term()
1260
1261              Encodes lists of action requests for one or more transaction re‐
1262              quest(s).
1263
1264              When encoding  action  requests  for  one  transaction,  Actions
1265              should  be action_reqs(). When encoding action requests for sev‐
1266              eral transactions, Actions should be [action_reqs()]. Each  ele‐
1267              ment of the list is part of one transaction.
1268
1269       token_tag2string(Tag) -> Result
1270       token_tag2string(Tag, EncoderMod) -> Result
1271       token_tag2string(Tag, EncoderMod, Version) -> Result
1272
1273              Types:
1274
1275                 Tag = atom()
1276                 EncoderMod = pretty | compact | encoder_module()
1277                 encoder_module()  =  megaco_pretty_text_encoder | megaco_com‐
1278                 pact_text_encoder | atom()
1279                 Version = int_version() | atom_version()
1280                 int_version() = 1 | 2 | 3
1281                 atom_version() = v1 | v2 | v3
1282                 Result = string() | {error, Reason}
1283                 Reason = term()
1284
1285              Convert a token tag to a string
1286
1287              If no encoder module is given, the default  is  used  (which  is
1288              pretty).
1289
1290              If  no  or an unknown version is given, the best version is used
1291              (which is v3).
1292
1293              If no match is found for Tag, Result will be  the  empty  string
1294              ([]).
1295
1296       cancel(ConnHandle, CancelReason) -> ok | {error, ErrReason}
1297
1298              Types:
1299
1300                 ConnHandle = conn_handle()
1301                 CancelReason = term()
1302                 ErrReason = term()
1303
1304              Cancel all outstanding messages for this connection
1305
1306              This  causes  outstanding  megaco:call/3 requests to return. The
1307              callback  functions  UserMod:handle_reply/4   and   UserMod:han‐
1308              dle_trans_ack/4  are  also  invoked  where  it  applies. See the
1309              megaco_user module for more info about the callback arguments.
1310
1311       process_received_message(ReceiveHandle, ControlPid, SendHandle, BinMsg)
1312       -> ok
1313       process_received_message(ReceiveHandle, ControlPid, SendHandle, BinMsg,
1314       Extra) -> ok
1315
1316              Types:
1317
1318                 ReceiveHandle = #megaco_receive_handle{}
1319                 ControlPid = pid()
1320                 SendHandle = term()
1321                 BinMsg = binary()
1322                 Extra = term()
1323
1324              Process a received message
1325
1326              This function is intended to be invoked by some  transport  mod‐
1327              ules when get an incoming message. Which transport that actually
1328              is used is up to the user to choose.
1329
1330              The message is delivered as an Erlang binary and is  decoded  by
1331              the  encoding  module stated in the receive handle together with
1332              its encoding config (also in the receive handle).  Depending  of
1333              the  outcome  of the decoding various callback functions will be
1334              invoked. See megaco_user for more info about the callback  argu‐
1335              ments.
1336
1337              The  argument  Extra  is just an opaque data structure passed to
1338              the user via the callback functions in the user callback module.
1339              Note however that if Extra has the value extra_undefined the ar‐
1340              gument will be ignored (same  as  if  process_received_message/4
1341              had been called). See the documentation for the behaviour of the
1342              callback module, megaco_user, for more info.
1343
1344              Note that all processing is done in the context of  the  calling
1345              process.  A transport module could call this function via one of
1346              the spawn functions  (e.g.  spawn_opt).  See  also  receive_mes‐
1347              sage/4,5.
1348
1349              If the message cannot be decoded the following callback function
1350              will be invoked:
1351
1352                * UserMod:handle_syntax_error/3
1353
1354              If the decoded message instead of transactions contains  a  mes‐
1355              sage error, the following callback function will be invoked:
1356
1357                * UserMod:handle_message_error/3
1358
1359              If the decoded message happens to be received before the connec‐
1360              tion is established, a new "virtual" connection is  established.
1361              This  is  typically  the  case  for the Media Gateway Controller
1362              (MGC) upon the first Service Change. When this occurs  the  fol‐
1363              lowing callback function will be invoked:
1364
1365                * UserMod:handle_connect/2
1366
1367              For  each transaction request in the decoded message the follow‐
1368              ing callback function will be invoked:
1369
1370                * UserMod:handle_trans_request/3
1371
1372              For each transaction reply in the decoded message the  reply  is
1373              returned   to   the   user.   Either  the  originating  function
1374              megaco:call/3 will return. Or in case the  originating  function
1375              was  megaco:case/3  the  following callback function will be in‐
1376              voked:
1377
1378                * UserMod:handle_trans_reply/4
1379
1380              When a transaction acknowledgement is received  it  is  possible
1381              that  user  has decided not to bother about the acknowledgement.
1382              But in case the return value from UserMod:handle_trans_request/3
1383              indicates  that  the  acknowledgement is important the following
1384              callback function will be invoked:
1385
1386                * UserMod:handle_trans_ack/4
1387
1388              See the megaco_user module for more info about the callback  ar‐
1389              guments.
1390
1391       receive_message(ReceiveHandle, ControlPid, SendHandle, BinMsg) -> ok
1392       receive_message(ReceiveHandle,  ControlPid,  SendHandle, BinMsg, Extra)
1393       -> ok
1394
1395              Types:
1396
1397                 ReceiveHandle = #megaco_receive_handle{}
1398                 ControlPid = pid()
1399                 SendHandle = term()
1400                 BinMsg = binary()
1401                 Extra = term()
1402
1403              Process a received message
1404
1405              This is a callback function  intended  to  be  invoked  by  some
1406              transport  modules when get an incoming message. Which transport
1407              that actually is used is up to the user to choose.
1408
1409              In principle, this function calls the process_received_message/4
1410              function via a spawn to perform the actual processing.
1411
1412              For further information see the process_received_message/4 func‐
1413              tion.
1414
1415       parse_digit_map(DigitMapBody) -> {ok, ParsedDigitMap} | {error, Reason}
1416
1417              Types:
1418
1419                 DigitMapBody = string()
1420                 ParsedDigitMap = parsed_digit_map()
1421                 parsed_digit_map() = term()
1422                 Reason = term()
1423
1424              Parses a digit map body
1425
1426              Parses a digit map body, represented as a  list  of  characters,
1427              into  a  list  of  state  transitions  suited to be evaluated by
1428              megaco:eval_digit_map/1,2.
1429
1430       eval_digit_map(DigitMap) -> {ok, MatchResult} | {error, Reason}
1431       eval_digit_map(DigitMap, Timers) -> {ok, MatchResult} | {error, Reason}
1432
1433              Types:
1434
1435                 DigitMap = #'DigitMapValue'{} | parsed_digit_map()
1436                 parsed_digit_map() = term()
1437                 ParsedDigitMap = term()
1438                 Timers = ignore() | reject()
1439                 ignore() = ignore | {ignore, digit_map_value()}
1440                 reject()   =   reject   |   {reject,   digit_map_value()}   |
1441                 digit_map_value()
1442                 MatchResult = {Kind, Letters} | {Kind, Letters, Extra}
1443                 Kind = kind()
1444                 kind() = full | unambiguous
1445                 Letters = [letter()]
1446                 letter() = $0..$9 | $a .. $k
1447                 Extra = letter()
1448                 Reason = term()
1449
1450              Collect digit map letters according to the digit map.
1451
1452              When  evaluating a digit map, a state machine waits for timeouts
1453              and letters reported by megaco:report_digit_event/2. The  length
1454              of  the  various  timeouts  are defined in the digit_map_value()
1455              record.
1456
1457              When a complete sequence of valid events has been received,  the
1458              result is returned as a list of letters.
1459
1460              There  are  two options for handling syntax errors (that is when
1461              an unexpected event is received when the digit map evaluator  is
1462              expecting some other event). The unexpected events may either be
1463              ignored or rejected. The latter means  that  the  evaluation  is
1464              aborted and an error is returned.
1465
1466       report_digit_event(DigitMapEvalPid, Events) -> ok | {error, Reason}
1467
1468              Types:
1469
1470                 DigitMapEvalPid = pid()
1471                 Events = Event | [Event]
1472                 Event = letter() | pause() | cancel()
1473                 letter() = $0..$9 | $a .. $k | $A .. $K
1474                 pause() = one_second() | ten_seconds()
1475                 one_second() = $s | $S
1476                 ten_seconds() = $l | $L
1477                 cancel() = $z | $Z | cancel
1478                 Reason = term()
1479
1480              Send one or more events to the event collector process.
1481
1482              Send  one or more events to a process that is evaluating a digit
1483              map,    that    is    a    process     that     is     executing
1484              megaco:eval_digit_map/1,2.
1485
1486              Note  that the events $s | $S, l | $L and $z | $Z has nothing to
1487              do with the timers using the same characters.
1488
1489       test_digit_event(DigitMap, Events) -> {ok,  Kind,  Letters}  |  {error,
1490       Reason}
1491
1492              Types:
1493
1494                 DigitMap = #'DigitMapValue'{} | parsed_digit_map()
1495                 parsed_digit_map() = term()
1496                 ParsedDigitMap = term()
1497                 Timers = ignore() | reject()
1498                 ignore() = ignore | {ignore, digit_map_value()}
1499                 reject()   =   reject   |   {reject,   digit_map_value()}   |
1500                 digit_map_value()
1501                 DigitMapEvalPid = pid()
1502                 Events = Event | [Event]
1503                 Event = letter() | pause() | cancel()
1504                 Kind = kind()
1505                 kind() = full | unambiguous
1506                 Letters = [letter()]
1507                 letter() = $0..$9 | $a .. $k | $A .. $K
1508                 pause() = one_second() | ten_seconds()
1509                 one_second() = $s | $S
1510                 ten_seconds() = $l | $L
1511                 cancel () = $z | $Z | cancel
1512                 Reason = term()
1513
1514              Feed digit map collector with events and return the result
1515
1516              This  function  starts  the  evaluation  of  a  digit  map  with
1517              megaco:eval_digit_map/1  and  sends  a  sequence of events to it
1518              megaco:report_digit_event/2 in  order  to  simplify  testing  of
1519              digit maps.
1520
1521       encode_sdp(SDP) -> {ok, PP} | {error, Reason}
1522
1523              Types:
1524
1525                 SDP  = sdp_property_parm() | sdp_property_group() | sdp_prop‐
1526                 erty_groups() | asn1_NOVALUE
1527                 PP = property_parm() | property_group() | property_groups() |
1528                 asn1_NOVALUE
1529                 Reason = term()
1530
1531              Encode (generate) an SDP construct.
1532
1533              If a property_parm() is found as part of the input (SDP) then it
1534              is left unchanged.
1535
1536              This function performs the following transformation:
1537
1538                * sdp() -> property_parm()
1539
1540                * sdp_property_group() -> property_group()
1541
1542                * sdp_property_groups() -> property_groups()
1543
1544       decode_sdp(PP) -> {ok, SDP} | {error, Reason}
1545
1546              Types:
1547
1548                 PP = property_parm() | property_group() | property_groups() |
1549                 asn1_NOVALUE
1550                 SDP  = sdp() | decode_sdp_property_group() | decode_sdp_prop‐
1551                 erty_groups() | asn1_NOVALUE
1552                 decode_sdp() = sdp() | {property_parm(), DecodeError}
1553                 decode_sdp_property_group() = [decode_sdp()]
1554                 decode_sdp_property_groups() = [decode_sdp_property_group()]
1555                 DecodeError = term()
1556                 Reason = term()
1557
1558              Decode (parse) a property parameter construct.
1559
1560              When decoding property_group() or property_groups(), those prop‐
1561              erty parameter constructs that cannot be decoded (either because
1562              of decode error or because they are unknown), will  be  returned
1563              as  a  two-tuple.  The first element of which will be the (unde‐
1564              coded) property parameter and the other the actual reason.  This
1565              means  that  the  caller of this function has to expect not only
1566              sdp-records, but also this two-tuple construct.
1567
1568              This function performs the following transformation:
1569
1570                * property_parm() -> sdp()
1571
1572                * property_group() -> sdp_property_group()
1573
1574                * property_groups() -> sdp_property_groups()
1575
1576       versions1() -> {ok, VersionInfo} | {error, Reason}
1577       versions2() -> {ok, Info} | {error, Reason}
1578
1579              Types:
1580
1581                 VersionInfo = [version_info()]
1582                 version_info() = term()
1583                 Reason = term()
1584
1585              Utility functions used to retrieve some system  and  application
1586              info.
1587
1588              The  difference between the two functions is in how they get the
1589              modules to check. versions1 uses the app-file and versions2 uses
1590              the function application:get_key.
1591
1592       print_version_info() -> void()
1593       print_version_info(VersionInfo) -> void()
1594
1595              Types:
1596
1597                 VersionInfo = [version_info()]
1598                 version_info() = term()
1599
1600              Utility  function to produce a formated printout of the versions
1601              info generated by the versions1 and versions2 functions.
1602
1603              The function print_version_info/0 uses the  result  of  function
1604              version1/0 as VersionInfo.
1605
1606              Example:
1607
1608                         {ok, V} = megaco:versions1(), megaco:format_versions(V).
1609
1610
1611       enable_trace(Level, Destination) -> void()
1612
1613              Types:
1614
1615                 Level = max | min | 0 <= integer() <= 100
1616                 Destination = File | Port | HandlerSpec | io
1617                 File = string()
1618                 Port = integer()
1619                 HandleSpec = {HandlerFun, Data}
1620                 HandleFun = fun() (two arguments)
1621                 Data = term()
1622
1623              This  function  is used to start megaco tracing at a given Level
1624              and direct result to the given Destination.
1625
1626              It starts a tracer server and then sets the  proper  match  spec
1627              (according to Level).
1628
1629              In the case when Destination is File, the printable megaco trace
1630              events will be printed to the file File using plain io:format/2.
1631
1632              In the case when Destination is io, the printable  megaco  trace
1633              events will be printed on stdout using plain io:format/2.
1634
1635              See dbg for further information.
1636
1637       disable_trace() -> void()
1638
1639              This function is used to stop megaco tracing.
1640
1641       set_trace(Level) -> void()
1642
1643              Types:
1644
1645                 Level = max | min | 0 <= integer() <= 100
1646
1647              This function is used to change the megaco trace level.
1648
1649              It  is  assumed  that  tracing has already been enabled (see en‐
1650              able_trace above).
1651
1652       get_stats() -> {ok, TotalStats} | {error, Reason}
1653       get_stats(GlobalCounter) -> {ok, CounterStats} | {error, Reason}
1654       get_stats(ConnHandle) -> {ok, ConnHandleStats} | {error, Reason}
1655       get_stats(ConnHandle, Counter) -> {ok, integer()} | {error, Reason}
1656
1657              Types:
1658
1659                 TotalStats = [total_stats()]
1660                 total_stats()     =     {conn_handle(),     [stats()]}      |
1661                 {global_counter(), integer()}
1662                 GlobalCounter = global_counter()
1663                 GlobalCounterStats = integer()
1664                 ConnHandle = conn_handle()
1665                 ConnHandleStats = [stats()]
1666                 stats() = {counter(), integer()}
1667                 Counter = counter()
1668                 counter()  = medGwyGatewayNumTimerRecovery | medGwyGatewayNu‐
1669                 mErrors
1670                 global_counter() = medGwyGatewayNumErrors
1671                 Reason = term()
1672
1673              Retreive the (SNMP) statistic counters maintained by the  megaco
1674              application.  The  global  counters handle events that cannot be
1675              attributed to a single connection (e.g. protocol errors that oc‐
1676              cur before the connection has been properly setup).
1677
1678       reset_stats() -> void()
1679       reset_stats(ConnHandle) -> void()
1680
1681              Types:
1682
1683                 ConnHandle = conn_handle()
1684
1685              Reset all related (SNMP) statistics counters.
1686
1687       test_request(ConnHandle, Version, EncodingMod, EncodingConfig, Actions)
1688       -> {MegaMsg, EncodeRes}
1689
1690              Types:
1691
1692                 ConnHandle = conn_handle()
1693                 Version = integer()
1694                 EncodingMod = atom()
1695                 EncodingConfig = Encoding configuration
1696                 Actions = A list
1697                 MegaMsg = #'MegacoMessage'{}
1698                 EncodeRes = {ok, Bin} | {error, Reason}
1699                 Bin = binary()
1700                 Reason = term()
1701
1702              Tests if the Actions argument is correctly composed.
1703
1704              This function is only intended for testing purposes.  It's  sup‐
1705              posed to have a same kind of interface as the call or cast func‐
1706              tions (with the additions of the EncodingMod and  EncodingConfig
1707              arguments).  It  composes a complete megaco message end attempts
1708              to encode it. The return value, will be a tuple of the  composed
1709              megaco message and the encode result.
1710
1711       test_reply(ConnHandle,  Version, EncodingMod, EncodingConfig, Reply) ->
1712       {MegaMsg, EncodeRes}
1713
1714              Types:
1715
1716                 ConnHandle = conn_handle()
1717                 Version = integer()
1718                 EncodingMod = atom()
1719                 EncodingConfig = A list
1720                 Reply = actual_reply()
1721                 MegaMsg = #'MegacoMessage'{}
1722                 EncodeRes = {ok, Bin} | {error, Reason}
1723                 Bin = binary()
1724                 Reason = term()
1725
1726              Tests if the Reply argument is correctly composed.
1727
1728              This function is only intended for testing purposes.  It's  sup‐
1729              posed  to  test  the actual_reply() return value of the callback
1730              functions  handle_trans_request  and   handle_trans_long_request
1731              functions  (with  the additions of the EncodingMod and Encoding‐
1732              Config arguments). It composes a complete megaco message end at‐
1733              tempts  to  encode  it. The return value, will be a tuple of the
1734              composed megaco message and the encode result.
1735
1736
1737
1738Ericsson AB                       megaco 4.3                         megaco(3)
Impressum