1megaco(3) Erlang Module Definition megaco(3)
2
6 megaco - Main API of the Megaco application
7
9 Interface module for the Megaco application
10
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 action_request() = #'ActionRequest'{}
23 action_reply() = #'ActionReply'{}
24 error_desc() = #'ErrorDescriptor'{}
25 transaction_reply() = #'TransactionReply'{}
26 segment_no() = integer()
27 resend_indication() = flag | boolean()
29 property_parm() = #'PropertyParm'{}
31 property_group() = [property_parm()]
32 property_groups() = [property_group()]
33 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 megaco_timer() = infinity | integer() >= 0 | megaco_incr_timer()
62 megaco_incr_timer() = #megaco_incr_timer{}
63 The record megaco_incr_timer contains the following fields:
66 wait_for = integer() >= 0:
68 The actual timer time.
69 factor = integer() >= 0:
71 The factor when calculating the new timer time (wait_for).
72 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 max_retries = infinity | infinity_restartable | integer() >= 0:
80 The maximum number of repetitions of the timer.
81 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
93 start() -> ok | {error, Reason}
94 Types:
96 Reason = term()
98 Starts the Megaco application
100 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 stop() -> ok | {error, Reason}
108 Types:
110 Reason = term()
112 Stops the Megaco application
114 start_user(UserMid, Config) -> ok | {error, Reason}
116 Types:
118 UserMid = megaco_mid()
120 Config = [{user_info_item(), user_info_value()}]
121 Reason = term()
122 Initial configuration of a user
124 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 A user is identified by its UserMid, which must be a legal
130 Megaco MID.
131 Config is a list of {Item, Value} tuples. See megaco:user_info/2
133 about which items and values that are valid.
134 stop_user(UserMid) -> ok | {error, Reason}
136 Types:
138 UserMid = megaco_mid()
140 Reason = term()
141 Delete the configuration of a user
143 Requires that the user does not have any active connection.
145 user_info(UserMid) -> [{Item, Value}]
147 user_info(UserMid, Item) -> Value | exit(Reason)
148 Types:
150 Handle = user_info_handle()
152 UserMid = megaco_mid()
153 Item = user_info_item()
154 Value = user_info_value()
155 Reason = term()
156 Lookup user information
158 The following Item's are valid:
160 connections:
162 Lists all active connections for this user. Returns a list
163 of megaco_conn_handle records.
164 receive_handle:
166 Construct a megaco_receive_handle record from user config
167 trans_id:
169 Current transaction id.
170 A positive integer or the atom undefined_serial (in case no
172 messages has been sent).
173 min_trans_id:
175 First trans id.
176 A positive integer, defaults to 1.
178 max_trans_id:
180 Last trans id.
181 A positive integer or infinity, defaults to infinity.
183 request_timer:
185 Wait for reply.
186 The timer is cancelled when a reply is received.
188 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 When the timer reaches an intermediate expire, the request
195 is resent and the timer is restarted.
196 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 A Megaco Timer (see explanation above), defaults to
203 #megaco_incr_timer{}.
204 long_request_timer:
206 Wait for reply after having received a pending message.
207 When the timer reaches an intermediate expire, the timer is
209 restarted.
210 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 A Megaco Timer (see explanation above), defaults to 60 sec‐
217 onds.
218 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 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 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 A boolean, defaults to false.
235 reply_timer:
237 Wait for an ack.
238 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 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 A Megaco Timer (see explanation above), defaults to 30000.
251 request_keep_alive_timeout:
253 Specifies the timeout time for the request-keep-alive timer.
254 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 Replies arriving after the timer has expired, will be deliv‐
263 ered using the handle_unexpected_trans/3,4 callback func‐
264 tion.
265 The timeout time can have the values: plain | integer() >=
267 0.
268 Defaults to plain.
270 call_proxy_gc_timeout:
272 Timeout time for the call proxy.
273 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 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 An integer >= 0, defaults to 5000 (= 5 seconds).
286 auto_ack:
288 Automatic send transaction ack when the transaction reply
289 has been received (see trans_ack below).
290 This is used for three-way-handshake.
292 A boolean, defaults to false.
294 trans_ack:
296 Shall ack's be accumulated or not.
297 This property is only valid if auto_ack is true.
299 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 See also transaction sender for more info.
308 An boolean, defaults to false.
310 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 See also transaction sender for more info.
317 An integer, defaults to 10.
319 trans_req:
321 Shall requests be accumulated or not.
322 If trans_req is false, then request(s) will be sent immedi‐
324 ately (in its own message).
325 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 See also transaction sender for more info.
332 An boolean, defaults to false.
334 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 See also transaction sender for more info.
341 An integer, defaults to 10.
343 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 See also transaction sender for more info.
350 An integer, defaults to 2048.
352 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 See also transaction sender for more info.
364 An integer, defaults to 0.
366 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 A Megaco Timer (see explanation above), defaults to 30000.
373 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 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 A positive integer or infinity, defaults to infinity.
390 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 A positive integer or infinity, defaults to infinity.
401 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 An atom, defaults to megaco_tcp.
408 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 An atom, defaults to megaco_pretty_text_encoder.
419 encoding_config:
421 Encoding module config.
422 A list, defaults to [].
424 protocol_version:
426 Actual protocol version.
427 An integer, default is 1.
429 strict_version:
431 Strict version control, i.e. when a message is received,
432 verify that the version is that which was negotiated.
433 An boolean, default is true.
435 reply_data:
437 Default reply data.
438 Any term, defaults to the atom undefined.
440 user_mod:
442 Name of the user callback module. See the the reference man‐
443 ual for megaco_user for more info.
444 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 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 An boolean, defaults to false.
457 resend_indication:
459 This option indicates weather the transport module should be
460 told if a message send is a resend or not.
461 If false, megaco messages are sent using the send_message
463 function.
464 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 The special value flag instead indicates that the function
470 send_message/3 shall be used.
471 A resend_indication(), defaults to false.
473 segment_reply_ind:
475 This option specifies if the user shall be notified of re‐
476 ceived segment replies or not.
477 See handle_segment_reply callback function for more informa‐
479 tion.
480 A boolean, defaults to false.
482 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 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 A Megaco Timer (see explanation above), defaults to 10000.
495 segment_send:
497 Shall outgoing messages be segmented or not:
498 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 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 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 Defaults to none.
518 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 A positive integer or infinity, defaults to infinity.
524 update_user_info(UserMid, Item, Value) -> ok | {error, Reason}
526 Types:
528 UserMid = megaco_mid()
530 Item = user_info_item()
531 Value = user_info_value()
532 Reason = term()
533 Update information about a user
535 Requires that the user is started. See megaco:user_info/2 about
537 which items and values that are valid.
538 conn_info(ConnHandle) -> [{Item, Value}]
540 conn_info(ConnHandle, Item) -> Value | exit(Reason)
541 Types:
543 ConnHandle = #megaco_conn_handle{}
545 Item = conn_info_item()
546 Value = conn_info_value()
547 Reason = {no_such_connection, ConnHandle} | term()
548 Lookup information about an active connection
550 Requires that the connection is active.
552 control_pid:
554 The process identifier of the controlling process for a con‐
555 nection.
556 send_handle:
558 Opaque send handle whose contents is internal for the send
559 module. May be any term.
560 local_mid:
562 The local mid (of the connection, i.e. the own mid).
563 megaco_mid().
564 remote_mid:
566 The remote mid (of the connection). megaco_mid().
567 receive_handle:
569 Construct a megaco_receive_handle record.
570 trans_id:
572 Next transaction id. A positive integer or the atom unde‐
573 fined_serial (only in case of error).
574 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 max_trans_id:
582 Last trans id.
583 A positive integer or infinity, defaults to infinity.
585 request_timer:
587 Wait for reply.
588 The timer is cancelled when a reply is received.
590 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 When the timer reaches an intermediate expire, the request
597 is resent and the timer is restarted.
598 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 A Megaco Timer (see explanation above), defaults to
605 #megaco_incr_timer{}.
606 long_request_timer:
608 Wait for reply after having received a pending message.
609 When the timer reaches an intermediate expire, the timer
611 restarted.
612 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 A Megaco Timer (see explanation above), defaults to 60 sec‐
619 onds.
620 request_keep_alive_timeout:
622 Specifies the timeout time for the request-keep-alive timer.
623 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 Replies arriving after the timer has expired, will be deliv‐
632 ered using the handle_unexpected_trans/3,4 callback func‐
633 tion.
634 The timeout time can have the values: plain | integer() >=
636 0.
637 Defaults to plain.
639 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 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 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 A boolean, defaults to false.
656 reply_timer:
658 Wait for an ack.
659 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 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 A Megaco Timer (see explanation above), defaults to 30000.
672 call_proxy_gc_timeout:
674 Timeout time for the call proxy.
675 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 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 An integer >= 0, defaults to 5000 (= 5 seconds).
688 auto_ack:
690 Automatic send transaction ack when the transaction reply
691 has been received (see trans_ack below).
692 This is used for three-way-handshake.
694 A boolean, defaults to false.
696 trans_ack:
698 Shall ack's be accumulated or not.
699 This property is only valid if auto_ack is true.
701 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 See also transaction sender for more info.
710 An boolean, defaults to false.
712 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 See also transaction sender for more info.
719 An integer, defaults to 10.
721 trans_req:
723 Shall requests be accumulated or not.
724 If trans_req is false, then request(s) will be sent immedi‐
726 ately (in its own message).
727 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 See also transaction sender for more info.
734 An boolean, defaults to false.
736 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 See also transaction sender for more info.
743 An integer, defaults to 10.
745 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 See also transaction sender for more info.
752 An integer, defaults to 2048.
754 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 See also transaction sender for more info.
766 An integer, defaults to 0.
768 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 A Megaco Timer (see explanation above), defaults to 30000.
775 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 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 A positive integer or infinity, defaults to infinity.
792 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 A positive integer or infinity, defaults to infinity.
803 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 An atom, defaults to megaco_tcp.
810 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 An atom, defaults to megaco_pretty_text_encoder.
821 encoding_config:
823 Encoding module config.
824 A list, defaults to [].
826 protocol_version:
828 Actual protocol version.
829 An positive integer, Current default is 1.
831 strict_version:
833 Strict version control, i.e. when a message is received,
834 verify that the version is that which was negotiated.
835 An boolean, default is true.
837 reply_data:
839 Default reply data.
840 Any term, defaults to the atom undefined.
842 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 An boolean, defaults to false.
851 resend_indication:
853 This option indicates weather the transport module should be
854 told if a message send is a resend or not.
855 If false, megaco messages are sent using the send_message/2
857 function.
858 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 The special value flag instead indicates that the function
864 send_message/3 shall be used.
865 A resend_indication(), defaults to false.
867 segment_reply_ind:
869 This option specifies if the user shall be notified of re‐
870 ceived segment replies or not.
871 See handle_segment_reply callback function for more informa‐
873 tion.
874 A boolean, defaults to false.
876 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 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 A Megaco Timer (see explanation above), defaults to 10000.
890 segment_send:
892 Shall outgoing messages be segmented or not:
893 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 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 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 Defaults to none.
913 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 A positive integer or infinity, defaults to infinity.
919 update_conn_info(ConnHandle, Item, Value) -> ok | {error, Reason}
921 Types:
923 ConnHandle = #megaco_conn_handle{}
925 Item = conn_info_item()
926 Value = conn_info_value()
927 Reason = term()
928 Update information about an active connection
930 Requires that the connection is activated. See
932 megaco:conn_info/2 about which items and values that are valid.
933 system_info() -> [{Item, Value}] | exit(Reason)
935 system_info(Item) -> Value | exit(Reason)
936 Types:
938 Item = system_info_item()
940 Lookup system information
942 The following items are valid:
944 text_config:
946 The text encoding config.
947 connections:
949 Lists all active connections. Returns a list of
950 megaco_conn_handle records.
951 users:
953 Lists all active users. Returns a list of megaco_mid()'s.
954 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 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 n_active_connections:
966 Returns an integer representing the number of active connec‐
967 tions.
968 info() -> Info
970 Types:
972 Info = [{Key, Value}]
974 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 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 connect(ReceiveHandle, RemoteMid, SendHandle, ControlPid) -> {ok,
984 ConnHandle} | {error, Reason}
985 connect(ReceiveHandle, RemoteMid, SendHandle, ControlPid, Extra) ->
986 {ok, ConnHandle} | {error, Reason}
987 Types:
989 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 Establish a "virtual" connection
1006 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 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 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 A connection may be established in several ways:
1035 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 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 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 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 An initial megaco_receive_handle record may be obtained with
1068 megaco:user_info(UserMid, receive_handle)
1069 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 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 connect_reason():
1081 An error with this reason is generated by the megaco appli‐
1082 cation itself.
1083 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 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 disconnect(ConnHandle, DiscoReason) -> ok | {error, ErrReason}
1094 Types:
1096 ConnHandle = conn_handle()
1098 DiscoReason = term()
1099 ErrReason = term()
1100 Tear down a "virtual" connection
1102 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 call(ConnHandle, Actions, Options) -> {ProtocolVersion, UserReply}
1108 Types:
1110 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 Sends one or more transaction request(s) and waits for the re‐
1158 ply.
1159 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 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 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 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 The ProtocolVersion version is the version actually encoded in
1179 the reply message.
1180 At success(), the UserReply contains a list of 'ActionReply'
1182 records possibly containing error indications.
1183 A message_error(), indicates that the remote user has replied
1185 with an explicit transactionError.
1186 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 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 An other_error(), indicates some other error such as timeout.
1199 For more info about the extra() part of the result, see the note
1201 in the user callback module documentation.
1202 cast(ConnHandle, Actions, Options) -> ok | {error, Reason}
1204 Types:
1206 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 Sends one or more transaction request(s) but does NOT wait for a
1220 reply
1221 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 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 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 The ProtocolVersion version is the version actually encoded in
1236 the reply message.
1237 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 Given as UserData argument to UserMod:handle_trans_reply/4.
1245 encode_actions(ConnHandle, Actions, Options) -> {ok, BinOrBins} | {er‐
1247 ror, Reason}
1248 Types:
1250 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 Encodes lists of action requests for one or more transaction re‐
1262 quest(s).
1263 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 token_tag2string(Tag) -> Result
1270 token_tag2string(Tag, EncoderMod) -> Result
1271 token_tag2string(Tag, EncoderMod, Version) -> Result
1272 Types:
1274 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 Convert a token tag to a string
1286 If no encoder module is given, the default is used (which is
1288 pretty).
1289 If no or an unknown version is given, the best version is used
1291 (which is v3).
1292 If no match is found for Tag, Result will be the empty string
1294 ([]).
1295 cancel(ConnHandle, CancelReason) -> ok | {error, ErrReason}
1297 Types:
1299 ConnHandle = conn_handle()
1301 CancelReason = term()
1302 ErrReason = term()
1303 Cancel all outstanding messages for this connection
1305 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 process_received_message(ReceiveHandle, ControlPid, SendHandle, BinMsg)
1312 -> ok
1313 process_received_message(ReceiveHandle, ControlPid, SendHandle, BinMsg,
1314 Extra) -> ok
1315 Types:
1317 ReceiveHandle = #megaco_receive_handle{}
1319 ControlPid = pid()
1320 SendHandle = term()
1321 BinMsg = binary()
1322 Extra = term()
1323 Process a received message
1325 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 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 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 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 If the message cannot be decoded the following callback function
1350 will be invoked:
1351 * UserMod:handle_syntax_error/3
1353 If the decoded message instead of transactions contains a mes‐
1355 sage error, the following callback function will be invoked:
1356 * UserMod:handle_message_error/3
1358 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 * UserMod:handle_connect/2
1366 For each transaction request in the decoded message the follow‐
1368 ing callback function will be invoked:
1369 * UserMod:handle_trans_request/3
1371 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 * UserMod:handle_trans_reply/4
1379 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 * UserMod:handle_trans_ack/4
1387 See the megaco_user module for more info about the callback ar‐
1389 guments.
1390 receive_message(ReceiveHandle, ControlPid, SendHandle, BinMsg) -> ok
1392 receive_message(ReceiveHandle, ControlPid, SendHandle, BinMsg, Extra)
1393 -> ok
1394 Types:
1396 ReceiveHandle = #megaco_receive_handle{}
1398 ControlPid = pid()
1399 SendHandle = term()
1400 BinMsg = binary()
1401 Extra = term()
1402 Process a received message
1404 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 In principle, this function calls the process_received_message/4
1410 function via a spawn to perform the actual processing.
1411 For further information see the process_received_message/4 func‐
1413 tion.
1414 parse_digit_map(DigitMapBody) -> {ok, ParsedDigitMap} | {error, Reason}
1416 Types:
1418 DigitMapBody = string()
1420 ParsedDigitMap = parsed_digit_map()
1421 parsed_digit_map() = term()
1422 Reason = term()
1423 Parses a digit map body
1425 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 eval_digit_map(DigitMap) -> {ok, MatchResult} | {error, Reason}
1431 eval_digit_map(DigitMap, Timers) -> {ok, MatchResult} | {error, Reason}
1432 Types:
1434 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 Collect digit map letters according to the digit map.
1451 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 When a complete sequence of valid events has been received, the
1458 result is returned as a list of letters.
1459 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 report_digit_event(DigitMapEvalPid, Events) -> ok | {error, Reason}
1467 Types:
1469 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 Send one or more events to the event collector process.
1481 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 Note that the events $s | $S, l | $L and $z | $Z has nothing to
1487 do with the timers using the same characters.
1488 test_digit_event(DigitMap, Events) -> {ok, Kind, Letters} | {error,
1490 Reason}
1491 Types:
1493 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 Feed digit map collector with events and return the result
1515 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 encode_sdp(SDP) -> {ok, PP} | {error, Reason}
1522 Types:
1524 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 Encode (generate) an SDP construct.
1532 If a property_parm() is found as part of the input (SDP) then it
1534 is left unchanged.
1535 This function performs the following transformation:
1537 * sdp() -> property_parm()
1539 * sdp_property_group() -> property_group()
1541 * sdp_property_groups() -> property_groups()
1543 decode_sdp(PP) -> {ok, SDP} | {error, Reason}
1545 Types:
1547 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 Decode (parse) a property parameter construct.
1559 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 This function performs the following transformation:
1569 * property_parm() -> sdp()
1571 * property_group() -> sdp_property_group()
1573 * property_groups() -> sdp_property_groups()
1575 versions1() -> {ok, VersionInfo} | {error, Reason}
1577 versions2() -> {ok, Info} | {error, Reason}
1578 Types:
1580 VersionInfo = [version_info()]
1582 version_info() = term()
1583 Reason = term()
1584 Utility functions used to retrieve some system and application
1586 info.
1587 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 print_version_info() -> void()
1593 print_version_info(VersionInfo) -> void()
1594 Types:
1596 VersionInfo = [version_info()]
1598 version_info() = term()
1599 Utility function to produce a formated printout of the versions
1601 info generated by the versions1 and versions2 functions.
1602 The function print_version_info/0 uses the result of function
1604 version1/0 as VersionInfo.
1605 Example:
1607 {ok, V} = megaco:versions1(), megaco:format_versions(V).
1609 enable_trace(Level, Destination) -> void()
1612 Types:
1614 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 This function is used to start megaco tracing at a given Level
1624 and direct result to the given Destination.
1625 It starts a tracer server and then sets the proper match spec
1627 (according to Level).
1628 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 In the case when Destination is io, the printable megaco trace
1633 events will be printed on stdout using plain io:format/2.
1634 See dbg for further information.
1636 disable_trace() -> void()
1638 This function is used to stop megaco tracing.
1640 set_trace(Level) -> void()
1642 Types:
1644 Level = max | min | 0 <= integer() <= 100
1646 This function is used to change the megaco trace level.
1648 It is assumed that tracing has already been enabled (see en‐
1650 able_trace above).
1651 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 Types:
1658 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 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 reset_stats() -> void()
1679 reset_stats(ConnHandle) -> void()
1680 Types:
1682 ConnHandle = conn_handle()
1684 Reset all related (SNMP) statistics counters.
1686 test_request(ConnHandle, Version, EncodingMod, EncodingConfig, Actions)
1688 -> {MegaMsg, EncodeRes}
1689 Types:
1691 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 Tests if the Actions argument is correctly composed.
1703 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 test_reply(ConnHandle, Version, EncodingMod, EncodingConfig, Reply) ->
1712 {MegaMsg, EncodeRes}
1713 Types:
1715 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 Tests if the Reply argument is correctly composed.
1727 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.
1735Ericsson AB megaco 4.5 megaco(3)