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