megaco_user(3erl) Erlang Module Definition megaco_user(3erl)
NAME
megaco_user - Callback module for users of the Megaco application
DESCRIPTION
This module defines the callback behaviour of Megaco users. A
megaco_user compliant callback module must export the following func-
tions:
* handle_connect/2,3
* handle_disconnect/3
* handle_syntax_error/3,4
* handle_message_error/3,4
* handle_trans_request/3,4
* handle_trans_long_request/3,4
* handle_trans_reply/4,5
* handle_trans_ack/4,5
* handle_unexpected_trans/3,4
* handle_trans_request_abort/4,5
* handle_segment_reply/5,6
The semantics of them and their exact signatures are explained below.
The user_args configuration parameter which may be used to extend the
argument list of the callback functions. For example, the handle_con-
nect function takes by default two arguments:
handle_connect(Handle, Version)
but if the user_args parameter is set to a longer list, such as
[SomePid,SomeTableRef], the callback function is expected to have these
(in this case two) extra arguments last in the argument list:
handle_connect(Handle, Version, SomePid, SomeTableRef)
Note:
Must of the functions below has an optional Extra argument (e.g. han-
dle_unexpected_trans/4). The functions which takes this argument will
be called if and only if one of the functions receive_message/5 or
process_received_message/5 was called with the Extra argument different
than ignore_extra.
DATA TYPES
action_request() = #'ActionRequest'{}
action_reply() = #'ActionReply'{}
error_desc() = #'ErrorDescriptor'{}
segment_no() = integer()
conn_handle() = #megaco_conn_handle{}
The record initially returned by megaco:connect/4,5. It identifies a
"virtual" connection and may be reused after a reconnect (disconnect +
connect).
protocol_version() = integer()
Is the actual protocol version. In most cases the protocol version is
retrieved from the processed message, but there are exceptions:
* When handle_connect/2,3 is triggered by an explicit call to
megaco:connect/4,5.
* handle_disconnect/3
* handle_syntax_error/3
In these cases, the ProtocolVersion default version is obtained from
the static connection configuration:
* megaco:conn_info(ConnHandle, protocol_version).
EXPORTS
handle_connect(ConnHandle, ProtocolVersion) -> ok | error | {error,Er-
rorDescr}
handle_connect(ConnHandle, ProtocolVersion, Extra) -> ok | error | {er-
ror,ErrorDescr}
Types:
ConnHandle = conn_handle()
ProtocolVersion = protocol_version()
ErrorDescr = error_desc()
Extra = term()
Invoked when a new connection is established
Connections may either be established by an explicit call to
megaco:connect/4 or implicitly at the first invocation of
megaco:receive_message/3.
Normally a Media Gateway (MG) connects explicitly while a Media
Gateway Controller (MGC) connects implicitly.
At the Media Gateway Controller (MGC) side it is possible to re-
ject a connection request (and send a message error reply to the
gateway) by returning {error, ErrorDescr} or simply error which
generates an error descriptor with code 402 (unauthorized) and
reason "Connection refused by user" (this is also the case for
all unknown results, such as exit signals or throw).
See note above about the Extra argument in handle_message_er-
ror/4.
handle_connect/3 (with Extra) can also be called as a result of
a call to the megaco:connect/5 function (if that function is
called with the Extra argument different than ignore_extra.
handle_disconnect(ConnHandle, ProtocolVersion, Reason) -> ok
Types:
ConnHandle = conn_handle()
ProtocolVersion = protocol_version()
Reason = term()
Invoked when a connection is teared down
The disconnect may either be made explicitly by a call to
megaco:disconnect/2 or implicitly when the control process of
the connection dies.
handle_syntax_error(ReceiveHandle, ProtocolVersion, DefaultED) -> reply
| {reply, ED} | no_reply | {no_reply, ED}
handle_syntax_error(ReceiveHandle, ProtocolVersion, DefaultED, Extra)
-> reply | {reply, ED} | no_reply | {no_reply, ED}
Types:
ReceiveHandle = receive_handle()
ProtocolVersion = protocol_version()
DefaultED = error_desc()
ED = error_desc()
Extra = term()
Invoked when a received message had syntax errors
Incoming messages is delivered by megaco:receive_message/4 and
normally decoded successfully. But if the decoding failed this
function is called in order to decide if the originator should
get a reply message (reply) or if the reply silently should be
discarded (no_reply).
Syntax errors are detected locally on this side of the protocol
and may have many causes, e.g. a malfunctioning transport layer,
wrong encoder/decoder selected, bad configuration of the se-
lected encoder/decoder etc.
The error descriptor defaults to DefaultED, but can be overrid-
den with an alternate one by returning {reply,ED} or {no_re-
ply,ED} instead of reply and no_reply respectively.
Any other return values (including exit signals or throw) and
the DefaultED will be used.
See note above about the Extra argument in handle_syntax_er-
ror/4.
handle_message_error(ConnHandle, ProtocolVersion, ErrorDescr) -> ok
handle_message_error(ConnHandle, ProtocolVersion, ErrorDescr, Extra) ->
ok
Types:
ConnHandle = conn_handle()
ProtocolVersion = protocol_version()
ErrorDescr = error_desc()
Extra = term()
Invoked when a received message just contains an error instead
of a list of transactions.
Incoming messages is delivered by megaco:receive_message/4 and
successfully decoded. Normally a message contains a list of
transactions, but it may instead contain an ErrorDescriptor on
top level of the message.
Message errors are detected remotely on the other side of the
protocol. And you probably don't want to reply to it, but it may
indicate that you have outstanding transactions that not will
get any response (request -> reply; reply -> ack).
See note above about the Extra argument in handle_message_er-
ror/4.
handle_trans_request(ConnHandle, ProtocolVersion, ActionRequests) ->
pending() | reply() | ignore_trans_request
handle_trans_request(ConnHandle, ProtocolVersion, ActionRequests, Ex-
tra) -> pending() | reply() | ignore_trans_request
Types:
ConnHandle = conn_handle()
ProtocolVersion = protocol_version()
ActionRequests = [action_request()]
Extra = term()
pending() = {pending, req_data()}
req_data() = term()
reply() = {ack_action(), actual_reply()} | {ack_action(), ac-
tual_reply(), send_options()}
ack_action() = discard_ack | {handle_ack, ack_data()} | {han-
dle_pending_ack, ack_data()} | {handle_sloppy_ack,
ack_data()}
actual_reply() = [action_reply()] | error_desc()
ack_data() = term()
send_options() = [send_option()]
send_option() = {reply_timer, megaco_timer()} | {send_handle,
term()} | {protocol_version, integer()}
Extra = term()
Invoked for each transaction request
Incoming messages is delivered by megaco:receive_message/4 and
successfully decoded. Normally a message contains a list of
transactions and this function is invoked for each Transaction-
Request in the message.
This function takes a list of 'ActionRequest' records and has
three main options:
Return ignore_trans_request:
Decide that these action requests shall be ignored com-
pletely.
Return pending():
Decide that the processing of these action requests will
take a long time and that the originator should get an imme-
diate 'TransactionPending' reply as interim response. The
actual processing of these action requests instead should be
delegated to the the handle_trans_long_request/3 callback
function with the req_data() as one of its arguments.
Return reply():
Process the action requests and either return an error_de-
scr() indicating some fatal error or a list of action
replies (wildcarded or not).
If for some reason megaco is unable to deliver the reply,
the reason for this will be passed to the user via a call to
the callback function handle_trans_ack, unless ack_action()
= discard_ack.
The ack_action() is either:
discard_ack:
Meaning that you don't care if the reply is acknowledged
or not.
{handle_ack, ack_data()} | {handle_ack, ack_data(), send_op-
tions()}:
Meaning that you want an immediate acknowledgement when
the other part receives this transaction reply. When the
acknowledgement eventually is received, the han-
dle_trans_ack/4 callback function will be invoked with the
ack_data() as one of its arguments. ack_data() may be any
Erlang term.
{handle_pending_ack, ack_data()} | {handle_pending_ack,
ack_data(), send_options()}:
This has the same effect as the above, if and only if
megaco has sent at least one pending message for this re-
quest (during the processing of the request). If no pend-
ing message has been sent, then immediate acknowledgement
will not be requested.
Note that this only works as specified if the sent_pend-
ing_limit config option has been set to an integer value.
{handle_sloppy_ack, ack_data()}| {handle_sloppy_ack,
ack_data(), send_options()}:
Meaning that you want an acknowledgement sometime. When
the acknowledgement eventually is received, the han-
dle_trans_ack/4 callback function will be invoked with the
ack_data() as one of its arguments. ack_data() may be any
Erlang term.
Any other return values (including exit signals or throw) will
result in an error descriptor with code 500 (internal gateway
error) and the module name (of the callback module) as reason.
See note above about the Extra argument in handle_trans_re-
quest/4.
handle_trans_long_request(ConnHandle, ProtocolVersion, ReqData) -> re-
ply()
handle_trans_long_request(ConnHandle, ProtocolVersion, ReqData, Extra)
-> reply()
Types:
ConnHandle = conn_handle()
ProtocolVersion = protocol_version()
ReqData = req_data()
Extra = term()
req_data() = term()
reply() = {ack_action(), actual_reply()} | {ack_action(), ac-
tual_reply(), send_options()}
ack_action() = discard_ack | {handle_ack, ack_data()} | {han-
dle_sloppy_ack, ack_data()}
actual_reply() = [action_reply()] | error_desc()
ack_data() = term()
send_options() = [send_option()]
send_option() = {reply_timer, megaco_timer()} | {send_handle,
term()} | {protocol_version, integer()}
Extra = term()
Optionally invoked for a time consuming transaction request
If this function gets invoked or not is controlled by the reply
from the preceding call to handle_trans_request/3. The han-
dle_trans_request/3 function may decide to process the action
requests itself or to delegate the processing to this function.
The req_data() argument to this function is the Erlang term re-
turned by handle_trans_request/3.
Any other return values (including exit signals or throw) will
result in an error descriptor with code 500 (internal gateway
error) and the module name (of the callback module) as reason.
See note above about the Extra argument in handle_trans_long_re-
quest/4.
handle_trans_reply(ConnHandle, ProtocolVersion, UserReply, ReplyData)
-> ok
handle_trans_reply(ConnHandle, ProtocolVersion, UserReply, ReplyData,
Extra) -> ok
Types:
ConnHandle = conn_handle()
ProtocolVersion = protocol_version()
UserReply = success() | failure()
success() = {ok, result()}
result() = transaction_result() | segment_result()
transaction_result() = action_reps()
segment_result() = {segment_no(), last_segment(), ac-
tion_reps()}
action_reps() = [action_reply()]
failure() = {error, reason()} | {error, ReplyNo, reason()}
reason() = transaction_reason() | segment_reason() |
user_cancel_reason() | send_reason() | other_reason()
transaction_reason() = error_desc()
segment_reason() = {segment_no(), last_segment(), er-
ror_desc()}
other_reason() = timeout | {segment_timeout, missing_seg-
ments()} | exceeded_recv_pending_limit | term()
last_segment() = bool()
missing_segments() = [segment_no()]
user_cancel_reason() = {user_cancel, reason_for_user_can-
cel()}
reason_for_user_cancel() = term()
send_reason() = send_cancelled_reason() | send_failed_rea-
son()
send_cancelled_reason() = {send_message_cancelled, rea-
son_for_send_cancel()}
reason_for_send_cancel() = term()
send_failed_reason() = {send_message_failed, rea-
son_for_send_failure()}
reason_for_send_failure() = term()
ReplyData = reply_data()
ReplyNo = integer() > 0
reply_data() = term()
Extra = term()
Optionally invoked for a transaction reply
The sender of a transaction request has the option of deciding,
whether the originating Erlang process should synchronously wait
(megaco:call/3) for a reply or if the message should be sent
asynchronously (megaco:cast/3) and the processing of the reply
should be delegated this callback function.
Note that if the reply is segmented (split into several smaller
messages; segments), then some extra info, segment number and an
indication if all segments of a reply has been received or not,
is also included in the UserReply.
The ReplyData defaults to megaco:lookup(ConnHandle, reply_data),
but may be explicitly overridden by a megaco:cast/3 option in
order to forward info about the calling context of the originat-
ing process.
At success(), the UserReply either contains:
* A list of 'ActionReply' records possibly containing error
indications.
* A tuple of size three containing: the segment number, the
last segment indicator and finally a list of 'ActionReply'
records possibly containing error indications. This is of
course only possible if the reply was segmented.
failure() indicates an local or external error and can be one of
the following:
* A transaction_reason(), indicates that the remote user has
replied with an explicit transactionError.
* A segment_reason(), indicates that the remote user has
replied with an explicit transactionError for this segment.
This is of course only possible if the reply was segmented.
* A user_cancel_reason(), indicates that the request has been
canceled by the user. reason_for_user_cancel() is the reason
given in the call to the cancel function.
* A send_reason(), indicates that the transport module
send_message function did not send the message. The reason
for this can be:
* send_cancelled_reason() - the message sending was deliber-
ately cancelled. reason_for_send_cancel() is the reason
given in the cancel return from the send_message function.
* send_failed_reason() - an error occurred while attempting
to send the message.
* An other_reason(), indicates some other error such as:
* timeout - the reply failed to arrive before the request
timer expired.
* {segment_timeout, missing_segments()} - one or more seg-
ments was not delivered before the expire of the segment
timer.
* exceeded_recv_pending_limit - the pending limit was ex-
ceeded for this request.
See note above about the Extra argument in handle_trans_reply/5.
handle_trans_ack(ConnHandle, ProtocolVersion, AckStatus, AckData) -> ok
handle_trans_ack(ConnHandle, ProtocolVersion, AckStatus, AckData, Ex-
tra) -> ok
Types:
ConnHandle = conn_handle()
ProtocolVersion = protocol_version()
AckStatus = ok | {error, reason()}
reason() = user_cancel_reason() | send_reason() | other_rea-
son()
user_cancel_reason() = {user_cancel, reason_for_user_can-
cel()}
send_reason() = send_cancelled_reason() | send_failed_rea-
son()
send_cancelled_reason() = {send_message_cancelled, rea-
son_for_send_cancel()}
reason_for_send_cancel() = term()
send_failed_reason() = {send_message_failed, rea-
son_for_send_failure()}
reason_for_send_failure() = term()
other_reason() = term()
AckData = ack_data()
ack_data() = term()
Extra = term()
Optionally invoked for a transaction acknowledgement
If this function gets invoked or not, is controlled by the reply
from the preceding call to handle_trans_request/3. The han-
dle_trans_request/3 function may decide to return {handle_ack,
ack_data()} or {handle_sloppy_ack, ack_data()} meaning that you
need an immediate acknowledgement of the reply and that this
function should be invoked to handle the acknowledgement.
The ack_data() argument to this function is the Erlang term re-
turned by handle_trans_request/3.
If the AckStatus is ok, it is indicating that this is a true ac-
knowledgement of the transaction reply.
If the AckStatus is {error, Reason}, it is an indication that
the acknowledgement or even the reply (for which this is an ac-
knowledgement) was not delivered, but there is no point in wait-
ing any longer for it to arrive. This happens when:
reply_timer:
The reply_timer eventually times out.
reply send failure:
When megaco fails to send the reply (see handle_trans_re-
ply), for whatever reason.
cancel:
The user has explicitly cancelled the wait (megaco:can-
cel/2).
See note above about the Extra argument in handle_trans_ack/5.
handle_unexpected_trans(ConnHandle, ProtocolVersion, Trans) -> ok
handle_unexpected_trans(ConnHandle, ProtocolVersion, Trans, Extra) ->
ok
Types:
ConnHandle = conn_handle()
ProtocolVersion = protocol_version()
Trans = #'TransactionPending'{} | #'TransactionReply'{} |
#'TransactionResponseAck'{}
Extra = term()
Invoked when a unexpected message is received
If a reply to a request is not received in time, the megaco
stack removes all info about the request from its tables. If a
reply should arrive after this has been done the app has no way
of knowing where to send this message. The message is delivered
to the "user" by calling this function on the local node (the
node which has the link).
See note above about the Extra argument in handle_unex-
pected_trans/4.
handle_trans_request_abort(ConnHandle, ProtocolVersion, TransNo, Pid)
-> ok
handle_trans_request_abort(ConnHandle, ProtocolVersion, TransNo, Pid,
Extra) -> ok
Types:
ConnHandle = conn_handle()
ProtocolVersion = protocol_version()
TransNo = integer()
Pid = undefined | pid()
Extra = term()
Invoked when a transaction request has been aborted
This function is invoked if the originating pending limit has
been exceeded. This usually means that a request has taken ab-
normally long time to complete.
See note above about the Extra argument in handle_trans_re-
quest_abort/5.
handle_segment_reply(ConnHandle, ProtocolVersion, TransNo, SegNo, Seg-
Compl) -> ok
handle_segment_reply(ConnHandle, ProtocolVersion, TransNo, SegNo, Seg-
Compl, Extra) -> ok
Types:
ConnHandle = conn_handle()
ProtocolVersion = protocol_version()
TransNo = integer()
SegNo = integer()
SegCompl = asn1_NOVALUE | 'NULL'
Extra = term()
This function is called when a segment reply has been received
if the segment_reply_ind config option has been set to true.
This is in effect a progress report.
See note above about the Extra argument in handle_segment_re-
ply/6.
Ericsson AB megaco 3.19.1 megaco_user(3erl)