Unix/Linux Go Back    


Linux 2.6 - man page for megaco_user (linux section 3erl)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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 call-
       back module must export the following functions:

	 * 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_connect function takes by default two argu-
       ments:

	       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. handle_unexpected_trans/4
       ).  The functions which takes this argument will be called if and only if one of the func-
       tions 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,ErrorDescr}
       handle_connect(ConnHandle, ProtocolVersion, Extra]) -> ok | error | {error,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  reject  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_error/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 dif-
	      ferent 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 selected encoder/decoder etc.

	      The error descriptor defaults to DefaultED , but can be overridden with  an  alter-
	      nate  one  by  returning	{reply,ED} or {no_reply,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_error/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 trans-
	      actions.

	      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_error/4 .

       handle_trans_request(ConnHandle, ProtocolVersion, ActionRequests) -> pending() | reply() |
       ignore_trans_request
       handle_trans_request(ConnHandle,  ProtocolVersion,  ActionRequests,  Extra) -> 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(),  actual_reply(),
		     send_options()}
		     ack_action() = discard_ack | {handle_ack, ack_data()} | {handle_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 TransactionRequest 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 completely.

		Return pending() :
		  Decide  that	the processing of these action requests will take a long time and
		  that the originator should  get  an  immediate  '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_descr() 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_options()} :
		    Meaning that you want  an  immediate  acknowledgement  when  the  other  part
		    receives  this  transaction  reply.  When  the  acknowledgement eventually is
		    received, the handle_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 request (during the processing of the
		    request). If no pending message has been sent, then immediate acknowledgement
		    will not be requested.

		    Note  that	this  only  works  as  specified if the sent_pending_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  handle_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 call-
	      back module) as reason.

	      See note above about the Extra argument in handle_trans_request/4 .

       handle_trans_long_request(ConnHandle, ProtocolVersion, ReqData) -> reply()
       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(),  actual_reply(),
		     send_options()}
		     ack_action()  = discard_ack | {handle_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()

	      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 handle_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 returned by han-
	      dle_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 call-
	      back module) as reason.

	      See note above about the Extra argument in handle_trans_long_request/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(), action_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(), error_desc()}
		     other_reason()   =   timeout   |	{segment_timeout,  missing_segments()}	|
		     exceeded_recv_pending_limit | term()
		     last_segment() = bool()
		     missing_segments() = [segment_no()]
		     user_cancel_reason() = {user_cancel, reason_for_user_cancel()}
		     reason_for_user_cancel() = term()
		     send_reason() = send_cancelled_reason() | send_failed_reason()
		     send_cancelled_reason() = {send_message_cancelled, reason_for_send_cancel()}
		     reason_for_send_cancel() = term()
		     send_failed_reason() = {send_message_failed, reason_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  origi-
	      nating 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; seg-
	      ments), 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 originating 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 indica-
		  tor and finally a list of 'ActionReply' records possibly containing error indi-
		  cations. 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 deliberately 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 mes-
		    sage.

		* 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 segments was  not  deliv-
		    ered before the expire of the segment timer.

		  * exceeded_recv_pending_limit  -  the  pending  limit  was  exceeded	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, Extra) -> ok

	      Types  ConnHandle = conn_handle()
		     ProtocolVersion = protocol_version()
		     AckStatus = ok | {error, reason()}
		     reason() = user_cancel_reason() | send_reason() | other_reason()
		     user_cancel_reason() = {user_cancel, reason_for_user_cancel()}
		     send_reason() = send_cancelled_reason() | send_failed_reason()
		     send_cancelled_reason() = {send_message_cancelled, reason_for_send_cancel()}
		     reason_for_send_cancel() = term()
		     send_failed_reason() = {send_message_failed, reason_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 handle_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  returned  by  han-
	      dle_trans_request/3.

	      If the AckStatus is ok, it is indicating that this is a true acknowledgement 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 acknowledgement) was not delivered, but
	      there is no point in waiting 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_reply	),  for  whatever
		  reason.

		cancel :
		  The user has explicitly cancelled the wait (megaco:cancel/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'{} | #'TransactionRe-
		     sponseAck'{}
		     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_unexpected_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 abnormally long time to complete.

	      See note above about the Extra argument in handle_trans_request_abort/5 .

       handle_segment_reply(ConnHandle, ProtocolVersion, TransNo, SegNo, SegCompl) -> ok
       handle_segment_reply(ConnHandle, ProtocolVersion, TransNo, SegNo, SegCompl, 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 seg-
	      ment_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_reply/6 .

Ericsson AB				  megaco 3.15.1 			megaco_user(3erl)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 05:31 PM.