megaco_user

模块

megaco_user

模块摘要

回调模块用于Megaco应用程序的用户

描述

该模块定义了Megaco用户的回调行为。符合megaco_user的回调模块必须导出以下函数：

• 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

下面将解释它们的语义和它们的确切签名。

user_args可用于扩展回调函数参数列表的配置参数。例如，handle_connect函数默认使用两个参数：

handle_connect(Handle, Version)

但是如果user_args参数设置为较长的​​列表，例如[SomePid,SomeTableRef]回调函数预期会在参数列表中包含这些（在此情况下为两个）额外参数：

handle_connect(Handle, Version, SomePid, SomeTableRef)

注意

下面的函数必须有一个可选的额外参数（例如handle_unexpected_trans / 4）。 当且仅当函数receive_message / 5或process_received_message / 5中的其中一个被调用时，Extra参数与ignore_extra不同，才会调用接受此参数的函数。

数据类型

action_request() = #'ActionRequest'{}
action_reply() = #'ActionReply'{}
error_desc() = #'ErrorDescriptor'{}
segment_no() = integer()

conn_handle() = #megaco_conn_handle{}    

记录最初由megaco:connect/4,5。它标识一个“虚拟”连接，并且可以在重新连接（断开连接+连接）后重新使用。

protocol_version() = integer()    

是实际的协议版本。在大多数情况下，协议版本是从处理的消息中检索的，但也有例外：

• handle_connect/2,3被明确的调用触发megaco:connect/4,5。
• handle_disconnect/3
• handle_syntax_error/3

在这些情况下，ProtocolVersion默认版本是从静态连接配置中获得的：

• megaco:conn_info(ConnHandle, protocol_version).

输出

handle_connect(ConnHandle, ProtocolVersion) -> ok | error | {error,ErrorDescr}handle_connect(ConnHandle, ProtocolVersion, Extra]) -> ok | error | {error,ErrorDescr}

类型

在建立新连接时调用

连接可以通过显式调用megaco来建立：connect / 4或者在第一次调用megaco时隐式地建立：receive_message / 3。

通常媒体网关（MG）在媒体网关控制器（MGC）隐式连接时明确连接。

在媒体网关控制器（MGC）侧，可以通过返回{error，ErrorDescr}或者仅仅是生成错误描述符的错误（代码402（未授权））来拒绝连接请求（并且向网关发送消息错误答复），并且 原因“用户拒绝连接”（这也适用于所有未知结果，例如退出信号或投掷）。

请参阅上面关于handle_message_error / 4中额外参数的注意事项。

由于调用了megaco：connect / 5函数（如果使用与ignore_extra不同的Extra参数调用该函数，也可以调用handle_connect / 3（带Extra）。

handle_disconnect(ConnHandle, ProtocolVersion, Reason) -> ok

类型

当连接被撤下时调用

可以通过调用megaco来显式断开连接：disconnect / 2，或者在连接的控制进程死亡时隐式断开。

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}

类型

当收到的消息有语法错误时调用

传入消息由megaco传递：receive_message / 4并正常解码成功。但是，如果解码失败，则调用此函数以决定发起者是否应该获得答复消息（答复），或者是否应该放弃答复（no_reply）。

语法错误在协议的这一端被本地检测到，并且可能有很多原因，例如传输层出现故障，选择了错误的编码器/解码器，所选编码器/解码器的配置错误等。

错误描述符默认为DefaultED，但可以通过分别返回{reply，ED}或{no_reply，ED}而不是使用reply和no_reply替代。

任何其他返回值（包括退出信号或抛出）和DefaultED将被使用。

请参阅note上文关于Extra参数handle_syntax_error/4。

handle_message_error(ConnHandle, ProtocolVersion, ErrorDescr) -> okhandle_message_error(ConnHandle, ProtocolVersion, ErrorDescr, Extra) -> ok

类型

当收到的消息只包含错误而不是事务列表时调用。

传入消息由megaco传递：receive_message / 4并成功解码。通常，消息包含事务列表，但它可能会在消息的顶层包含ErrorDescriptor。

在协议的另一端远程检测到消息错误。你可能不想回复它，但它可能表明你有未完成的交易，不会得到任何回应（请求 - >回复;回复 - > ack）。

请参阅note上文关于Extra参数handle_message_error/4。

handle_trans_request(ConnHandle, ProtocolVersion, ActionRequests) -> pending() | reply() | ignore_trans_requesthandle_trans_request(ConnHandle, ProtocolVersion, ActionRequests, Extra) -> pending() | reply() | ignore_trans_request

类型

为每个事务请求调用

传入消息由megaco传递：receive_message / 4并成功解码。通常，消息包含事务列表，并且此消息中的每个TransactionRequest都会调用此函数。

该功能采用“ActionRequest”记录列表，并有三个主要选项：

Return ignore_trans_request

决定完全忽略这些行动请求。

Return pending()

决定处理这些行动请求需要很长时间，发起人应该立即获得“TransactionPending”答复作为临时答复。这些动作请求的实际处理应该委托给handle_trans_long_request / 3回调函数，并将req_data（）作为其参数之一。

Return reply()

处理动作请求，并返回一个error_descr（），指示一些致命错误或动作答复列表（通配符或不通配符）。

如果由于某种原因，megaco无法提供答复，其原因将通过调用回调函数传递给用户handle_trans_ack，除非ack_action() = discard_ack。

ack_action（）可以是：

discard_ack

这意味着你不关心回复是否被确认。

{handle_ack, ack_data()} | {handle_ack, ack_data(), send_options()}

这意味着您希望在另一部分收到此交易回复时立即确认。当最终收到确认时，将使用ack_data（）作为其参数之一来调用handle_trans_ack / 4回调函数。ack_data（）可以是任何Erlang术语。

{handle_pending_ack, ack_data()} | {handle_pending_ack, ack_data(), send_options()}

这与上述效果相同，当且仅当 megaco已经为此请求发送了至少一个待处理消息时（处理请求期间）。如果未发送待处理消息，则不会请求即时确认。

请注意，只有在sent_pending_limit配置选项已设置为整数值的情况下，才能按照指定的方式工作。

{handle_sloppy_ack, ack_data()}| {handle_sloppy_ack, ack_data(), send_options()}

这意味着你要确认某个时候。当最终收到确认时，将使用ack_data（）作为其参数之一来调用handle_trans_ack / 4回调函数。ack_data（）可以是任何Erlang术语。

任何其他返回值（包括退出信号或throw）都会导致一个代码为500（内部网关错误）的错误描述符和（回调模块的）模块名称为原因。

请参阅note上文关于Extra参数handle_trans_request/4。

handle_trans_long_request(ConnHandle, ProtocolVersion, ReqData) -> reply()handle_trans_long_request(ConnHandle, ProtocolVersion, ReqData, Extra) -> reply()

类型

可选地调用一个耗时的事务请求

如果这个函数被调用或者不被前面调用handle_trans_request / 3的应答控制。handle_trans_request / 3函数可以决定自己处理动作请求，或者将处理委托给该函数。

该函数的req_data（）参数是handle_trans_request / 3返回的Erlang项。

任何其他返回值（包括退出信号或throw）都会导致一个代码为500（内部网关错误）的错误描述符和（回调模块的）模块名称为原因。

请参阅note上文关于Extra参数handle_trans_long_request/4。

handle_trans_reply(ConnHandle, ProtocolVersion, UserReply, ReplyData) -> okhandle_trans_reply(ConnHandle, ProtocolVersion, UserReply, ReplyData, Extra) -> ok

类型

可选地为事务回复调用

事务请求的发送者可以选择决定，发起的Erlang进程是否应该同步等待（megaco:call/3）回复，或者消息是否应该异步发送（megaco:cast/3），并且回复的处理应该委托给这个回调函数。

请注意，如果回复是分段的（分成几个较小的消息;分段），那么一些额外的信息，分段号码和一个指示是否已收到回复的所有分段，也包括在UserReply内。

ReplyData默认为megaco：lookup（ConnHandle，reply_data），但可能会被megaco：cast / 3选项显式覆盖，以转发关于始发进程的调用上下文的信息。

在success（）中，UserReply包含：

• 可能包含错误指示的'ActionReply'记录列表。
• 大小为3的元组包含：段编号，last segment indicator最后是可能包含错误指示的“ActionReply”记录列表。这当然只有在答复被分割时才有可能。

failure() 表示本地或外部错误，可以是以下之一：

• transaction_reason()表示远程用户已用显式的transactionError回复。
• segment_reason()，表示远程用户已回复此段的显式transactionError。这当然只有在答复被分割时才有可能。
• user_cancel_reason()表示请求已被用户取消。reason_for_user_cancel()是在cancel函数调用中给出的原因。
• send_reason()，表示传输模块send_message功能没有发送消息。其原因可以是：

-  `send_cancelled_reason()` - the message sending was deliberately cancelled. `reason_for_send_cancel()` is the reason given in the `cancel` return from the [`send_message`](megaco_transport#send_message) function. 

-  `send_failed_reason()` - an error occurred while attempting to send the message. 

• other_reason()，表示其他一些错误，例如：

-  `timeout` - the reply failed to arrive before the request timer expired.

-  `{segment_timeout, missing_segments()}` - one or more segments was not delivered before the expire of the segment timer.

-  `exceeded_recv_pending_limit` - the pending limit was exceeded for this request.

请参阅note上文关于Extra参数handle_trans_reply/5。

handle_trans_ack(ConnHandle, ProtocolVersion, AckStatus, AckData) -> okhandle_trans_ack(ConnHandle, ProtocolVersion, AckStatus, AckData, Extra) -> ok

类型

可选地为事务确认调用

如果该函数被调用或者不被调用，则由前面调用handle_trans_request / 3的应答来控制。handle_trans_request / 3函数可能决定返回{handle_ack，ack_data（）}或{handle_sloppy_ack，ack_data（）}，这意味着您需要立即确认答复，并且应调用此函数来处理确认。

该函数的ack_data（）参数是由handle_trans_request / 3返回的Erlang术语。

如果AckStatus正确，则表示这是对事务回复的确认。

如果AckStatus是{error，Reason}，则表示确认或甚至答复（这是确认）没有交付，但没有时间等待它到达。发生这种情况时：

reply_timer

该reply_timer最终超时。

回复发送失败

当megaco未能发送答复（见handle_trans_reply）时，无论出于何种原因。

取消

用户已明确取消等待（megaco：取消/ 2）。

请参阅note上文关于Extra参数handle_trans_ack/5。

handle_unexpected_trans(ConnHandle, ProtocolVersion, Trans) -> okhandle_unexpected_trans(ConnHandle, ProtocolVersion, Trans, Extra) -> ok

类型

在收到意外消息时调用

如果未及时收到对请求的回复，则megaco堆栈会从其表中删除有关请求的所有信息。如果在完成此操作后应答应答，则应用无法知道该消息的发送位置。通过在本地节点（具有链接的节点）上调用此函数将消息传递给“用户”。

请参阅上面关于handle_unexpected_trans / 4中额外参数的注释。

handle_trans_request_abort(ConnHandle, ProtocolVersion, TransNo, Pid) -> okhandle_trans_request_abort(ConnHandle, ProtocolVersion, TransNo, Pid, Extra) -> ok

类型

当事务请求被中止时调用

如果超过原始挂起限制，则调用此函数。这通常意味着请求花了很长时间才能完成。

请参阅note上文关于Extra参数handle_trans_request_abort/5。

handle_segment_reply(ConnHandle, ProtocolVersion, TransNo, SegNo, SegCompl) -> okhandle_segment_reply(ConnHandle, ProtocolVersion, TransNo, SegNo, SegCompl, Extra) -> ok

Types

如果segment_reply_ind配置选项已设置为true，则在收到段回复时调用此函数。

This is in effect a progress report.

请参阅note上文关于Extra参数handle_segment_reply/6。