[megaco] Add megaco_user behaviour module

Add a "proper" behaviour module for the megaco_user behaviour.
This behaviour is not a proper behaviour since its possible to
configure megaco to add additional arguments to *all* of the
functions in the behaviour (with the user_args config option).
So, this behaviour only reflects the *default config* (whith
the user_args set to [], that is no extra args).

OTP-15882

5 files changed, 412 insertions, 10 deletions

diff --git a/lib/megaco/src/app/megaco.erl b/lib/megaco/src/app/megaco.erl
index 756f4929d3..9ed042401b 100644
--- a/lib/megaco/src/app/megaco.erl
+++ b/lib/megaco/src/app/megaco.erl
@@ -94,6 +94,11 @@
 %% This is for XREF
 -deprecated([{format_versions, 1, eventually}]).
 
+-export_type([
+              void/0
+             ]).
+
+-type void() :: term().
 
 -include("megaco_internal.hrl").
 
diff --git a/lib/megaco/src/engine/depend.mk b/lib/megaco/src/engine/depend.mk
index 96ee337e3a..ba919659db 100644
--- a/lib/megaco/src/engine/depend.mk
+++ b/lib/megaco/src/engine/depend.mk
@@ -2,7 +2,7 @@
 
 # %CopyrightBegin%
 # 
-# Copyright Ericsson AB 2003-2016. All Rights Reserved.
+# Copyright Ericsson AB 2003-2019. All Rights Reserved.
 # 
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -78,6 +78,10 @@ $(EBIN)/megaco_transport.$(EMULATOR): megaco_transport.erl
 
 $(EBIN)/megaco_user.$(EMULATOR): megaco_user.erl
 
+$(EBIN)/megaco_user.$(EMULATOR): megaco_user.erl \
+	../../include/megaco.hrl \
+	../../include/megaco_message_v1.hrl
+
 $(EBIN)/megaco_user_default.$(EMULATOR): megaco_user_default.erl \
 	../../include/megaco.hrl \
 	../../include/megaco_message_v1.hrl
diff --git a/lib/megaco/src/engine/megaco_encoder.erl b/lib/megaco/src/engine/megaco_encoder.erl
index 04f517d07c..dd5a3458fc 100644
--- a/lib/megaco/src/engine/megaco_encoder.erl
+++ b/lib/megaco/src/engine/megaco_encoder.erl
@@ -26,6 +26,8 @@
 -module(megaco_encoder).
 
 -export_type([
+              protocol_version/0,
+              segment_no/0,
               megaco_message/0,
               transaction/0,
               transaction_request/0,
@@ -36,12 +38,15 @@
               segment_reply/0,
               action_request/0,
               action_reply/0,
-              command_request/0
+              command_request/0,
+              error_desc/0
              ]).
 
 
 -include("megaco_message_internal.hrl").
 
+-type protocol_version() :: integer().
+-type segment_no()       :: integer().
 -type megaco_message() :: #'MegacoMessage'{}.
 -type transaction()    :: {transactionRequest,     transaction_request()}      |
                           {transactionPending,     transaction_reply()}        |
@@ -64,13 +69,14 @@
 %% -type action_reply()             :: #'ActionReply'{}.
 -type action_reply()             :: {'ActionReply', _, _, _}.
 %% -type command_request()           :: #'CommandRequest'{}.
--type command_request()           :: {'CommandRequest', _, _, _}.
+-type command_request()          :: {'CommandRequest', _, _, _}.
+-type error_desc()               :: #'ErrorDescriptor'{}.
 
 -callback encode_message(EncodingConfig,
                          Version,
                          Message) -> {ok, Bin} | Error when
       EncodingConfig :: list(),
-      Version        :: integer(),
+      Version        :: protocol_version(),
       Message        :: megaco_message(),
       Bin            :: binary(),
       Error          :: term().
@@ -79,7 +85,7 @@
                          Version,
                          Bin) -> {ok, Message} | Error when
       EncodingConfig :: list(),
-      Version        :: integer() | dynamic,
+      Version        :: protocol_version() | dynamic,
       Bin            :: binary(),
       Message        :: megaco_message(),
       Error          :: term().
@@ -88,7 +94,7 @@
                               Version,
                               Bin) -> {ok, Message} | Error when
       EncodingConfig :: list(),
-      Version        :: integer() | dynamic,
+      Version        :: protocol_version() | dynamic,
       Bin            :: binary(),
       Message        :: megaco_message(),
       Error          :: term().
@@ -97,7 +103,7 @@
                              Version,
                              Transaction) -> {ok, Bin} | {error, Reason} when
       EncodingConfig :: list(),
-      Version        :: integer(),
+      Version        :: protocol_version(),
       Transaction    :: transaction(),
       Bin            :: binary(),
       Reason         :: not_implemented | term().
@@ -106,7 +112,7 @@
                                  Version,
                                  ARs) -> {ok, Bin} | {error, Reason} when
       EncodingConfig :: list(),
-      Version        :: integer(),
+      Version        :: protocol_version(),
       ARs            :: [action_request()],
       Bin            :: binary(),
       Reason         :: not_implemented | term().
@@ -115,7 +121,7 @@
                               Version,
                               AR) -> {ok, Bin} | {error, Reason} when
       EncodingConfig :: list(),
-      Version        :: integer(),
+      Version        :: protocol_version(),
       AR             :: action_reply(),
       Bin            :: binary(),
       Reason         :: not_implemented | term().
diff --git a/lib/megaco/src/engine/megaco_user.erl b/lib/megaco/src/engine/megaco_user.erl
new file mode 100644
index 0000000000..47fb1a119d
--- /dev/null
+++ b/lib/megaco/src/engine/megaco_user.erl
@@ -0,0 +1,386 @@
+%%
+%% %CopyrightBegin%
+%% 
+%% Copyright Ericsson AB 2019-2019. All Rights Reserved.
+%% 
+%% Licensed under the Apache License, Version 2.0 (the "License");
+%% you may not use this file except in compliance with the License.
+%% You may obtain a copy of the License at
+%%
+%%     http://www.apache.org/licenses/LICENSE-2.0
+%%
+%% Unless required by applicable law or agreed to in writing, software
+%% distributed under the License is distributed on an "AS IS" BASIS,
+%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+%% See the License for the specific language governing permissions and
+%% limitations under the License.
+%% 
+%% %CopyrightEnd%
+%%
+
+%%
+%%-------------------------------------------------------------------------
+%% Purpose: Megaco user behaviour module
+%%
+%% This callback functions are the default! Its possible for the user to
+%% provide a arbitrary number of "extra" arguments via the user_args
+%% config option.
+%% So, for instance, the handle_connect/2 could instead become
+%% handle_connect/4 if the user sets the user_args option to [foo, bar].
+%% This means that its impossible to define a proper behaviour.
+%% So what we do here is to define a behaviour with the "default interface"
+%% (the user_args option has the [] as the default value) and set them
+%% all to be optional!
+%%-------------------------------------------------------------------------
+
+-module(megaco_user).
+
+-export_type([
+              receive_handle/0,
+              conn_handle/0,
+              megaco_timer/0
+             ]).
+
+-include_lib("megaco/include/megaco.hrl").
+%% -include_lib("megaco/include/megaco_message_v1.hrl").
+
+-type receive_handle() :: #megaco_receive_handle{}.
+-type conn_handle()    :: #megaco_conn_handle{}.
+-type megaco_timer()   :: infinity | non_neg_integer() | #megaco_incr_timer{}.
+
+-callback handle_connect(ConnHandle, ProtocolVersion) -> 
+    ok | error | {error, ErrorDescr} when
+      ConnHandle      :: conn_handle(),
+      ProtocolVersion :: megaco_encoder:protocol_version(),
+      ErrorDescr      :: megaco_encoder:error_desc().
+-callback handle_connect(ConnHandle, ProtocolVersion, Extra) -> 
+    ok | error | {error, ErrorDescr} when
+      ConnHandle      :: conn_handle(),
+      ProtocolVersion :: megaco_encoder:protocol_version(),
+      Extra           :: term(),
+      ErrorDescr      :: megaco_encoder:error_desc().
+
+-callback handle_disconnect(ConnHandle, ProtocolVersion, Reason) ->
+    megaco:void() when
+      ConnHandle      :: conn_handle(),
+      ProtocolVersion :: megaco_encoder:protocol_version(),
+      Reason          :: term().
+
+-callback handle_syntax_error(ReceiveHandle, ProtocolVersion, DefaultED) -> 
+    reply | {reply, ED} | no_reply | {no_reply, ED} when
+      ReceiveHandle   :: receive_handle(),
+      ProtocolVersion :: megaco_encoder:protocol_version(),
+      DefaultED       :: megaco_encoder:error_desc(),
+      ED              :: megaco_encoder:error_desc().
+-callback handle_syntax_error(ReceiveHandle, ProtocolVersion, DefaultED, Extra) -> 
+    reply | {reply, ED} | no_reply | {no_reply, ED} when
+      ReceiveHandle   :: receive_handle(),
+      ProtocolVersion :: megaco_encoder:protocol_version(),
+      DefaultED       :: megaco_encoder:error_desc(),
+      ED              :: megaco_encoder:error_desc(),
+      Extra           :: term().
+
+-callback handle_message_error(ConnHandle, ProtocolVersion, ErrorDescr) ->
+    megaco:void() when
+      ConnHandle      :: conn_handle(),
+      ProtocolVersion :: megaco_encoder:protocol_version(),
+      ErrorDescr      :: megaco_encoder:error_desc().
+-callback handle_message_error(ConnHandle, ProtocolVersion, ErrorDescr, Extra) ->
+    megaco:void() when
+      ConnHandle      :: conn_handle(),
+      ProtocolVersion :: megaco_encoder:protocol_version(),
+      ErrorDescr      :: megaco_encoder:error_desc(),
+      Extra           :: term().
+
+-callback handle_trans_request(ConnHandle, ProtocolVersion, ActionRequests) ->
+    Pending | Reply | ignore_trans_request when
+      ConnHandle      :: conn_handle(),
+      ProtocolVersion :: megaco_encoder:protocol_version(),
+      ActionRequests  :: [megaco_encoder:action_request()],
+      Pending         :: {pending, ReqData},
+      ReqData         :: term(),
+      Reply           :: {AckAction, ActualReply} |
+                         {AckAction, ActualReply, SendOptions},
+      AckAction       :: discard_ack |
+                         {handle_ack,         AckData} |
+                         {handle_pending_ack, AckData} |
+                         {handle_sloppy_ack,  AckData},
+      ActualReply     :: [megaco_encoder:action_reply()] |
+                         megaco_encoder:error_desc(),
+      AckData         :: term(),
+      SendOptions     :: [SendOption],
+      SendOption      :: {reply_timer,      megaco_timer()} |
+                         {send_handle,      term()} |
+                         {protocol_version, integer()}.
+-callback handle_trans_request(ConnHandle,
+                               ProtocolVersion,
+                               ActionRequests,
+                               Extra) ->
+    Pending | Reply | ignore_trans_request when
+      ConnHandle      :: conn_handle(),
+      ProtocolVersion :: megaco_encoder:protocol_version(),
+      ActionRequests  :: [megaco_encoder:action_request()],
+      Extra           :: term(),
+      Pending         :: {pending, ReqData},
+      ReqData         :: term(),
+      Reply           :: {AckAction, ActualReply} |
+                         {AckAction, ActualReply, SendOptions},
+      AckAction       :: discard_ack |
+                         {handle_ack,         AckData} |
+                         {handle_pending_ack, AckData} |
+                         {handle_sloppy_ack,  AckData},
+      ActualReply     :: [megaco_encoder:action_reply()] |
+                         megaco_encoder:error_desc(),
+      AckData         :: term(),
+      SendOptions     :: [SendOption],
+      SendOption      :: {reply_timer,      megaco_timer()} |
+                         {send_handle,      term()} |
+                         {protocol_version, integer()}.
+
+-callback handle_trans_long_request(ConnHandle, ProtocolVersion, ReqData) ->
+    Reply when
+      ConnHandle      :: conn_handle(),
+      ProtocolVersion :: megaco_encoder:protocol_version(),
+      ReqData         :: term(),
+      Reply           :: {AckAction, ActualReply} |
+                         {AckAction, ActualReply, SendOptions},
+      AckAction       :: discard_ack |
+                         {handle_ack, AckData} |
+                         {handle_sloppy_ack, AckData},
+      ActualReply     :: [megaco_encoder:action_reply()] |
+                         megaco_encoder:error_desc(),
+      AckData         :: term(),
+      SendOptions     :: [SendOption],
+      SendOption      :: {reply_timer, megaco_timer()} |
+                         {send_handle, term()} |
+                         {protocol_version, megaco_encoder:protocol_version()}.
+-callback handle_trans_long_request(ConnHandle, ProtocolVersion, ReqData, Extra) ->
+    Reply when
+      ConnHandle      :: conn_handle(),
+      ProtocolVersion :: megaco_encoder:protocol_version(),
+      ReqData         :: term(),
+      Extra           :: term(),
+      Reply           :: {AckAction, ActualReply} |
+                         {AckAction, ActualReply, SendOptions},
+      AckAction       :: discard_ack |
+                         {handle_ack, AckData} |
+                         {handle_sloppy_ack, AckData},
+      ActualReply     :: [megaco_encoder:action_reply()] |
+                         megaco_encoder:error_desc(),
+      AckData         :: term(),
+      SendOptions     :: [SendOption],
+      SendOption      :: {reply_timer, megaco_timer()} |
+                         {send_handle, term()} |
+                         {protocol_version, megaco_encoder:protocol_version()}.
+
+-callback handle_trans_reply(ConnHandle,
+                             ProtocolVersion,
+                             UserReply,
+                             ReplyData) ->
+    ok when
+      ConnHandle           :: conn_handle(),
+      ProtocolVersion      :: megaco_encoder:protocol_version(),
+      UserReply            :: Success | Failure,
+      ReplyData            :: term(),
+      Success              :: {ok, Result},
+      Result               :: TransactionResult | SegmentResult,
+      TransactionResult    :: [megaco_encoder:action_reply()],
+      SegmentResult        :: {megaco_encoder:segment_no(),
+                               LastSegment,
+                               [megaco_encoder:action_reply()]},
+      Failure              :: {error, Reason} |
+                              {error, ReplyNo, Reason},
+      Reason               :: TransactionReason |
+                              SegmentReason |
+                              UserCancelReason |
+                              SendReason |
+                              OtherReason,
+      TransactionReason    :: megaco_encoder:error_desc(),
+      SegmentReason        :: {megaco_encoder:segment_no(),
+                               LastSegment,
+                               megaco_encoder:error_desc()},
+      OtherReason          :: timeout |
+                              {segment_timeout, MissingSegments} |
+                              exceeded_recv_pending_limit | term(),
+      LastSegment          :: boolean(),
+      MissingSegments      :: [megaco_encoder:segment_no()],
+      UserCancelReason     :: {user_cancel, ReasonForUserCancel},
+      ReasonForUserCancel  :: term(),
+      SendReason           :: SendCancelledReason | SendFailedReason,
+      SendCancelledReason  :: {send_message_cancelled,
+                               ReasonForSendCancel},
+      ReasonForSendCancel  :: term(),
+      SendFailedReason     :: {send_message_failed, ReasonForSendFailure},
+      ReasonForSendFailure :: term(),
+      ReplyNo              :: pos_integer().
+-callback handle_trans_reply(ConnHandle,
+                             ProtocolVersion,
+                             UserReply,
+                             ReplyData,
+                             Extra) ->
+    ok when
+      ConnHandle           :: conn_handle(),
+      ProtocolVersion      :: megaco_encoder:protocol_version(),
+      UserReply            :: Success | Failure,
+      ReplyData            :: term(),
+      Extra                :: term(),
+      Success              :: {ok, Result},
+      Result               :: TransactionResult | SegmentResult,
+      TransactionResult    :: [megaco_encoder:action_reply()],
+      SegmentResult        :: {megaco_encoder:segment_no(),
+                               LastSegment,
+                               [megaco_encoder:action_reply()]},
+      Failure              :: {error, Reason} |
+                              {error, ReplyNo, Reason},
+      Reason               :: TransactionReason |
+                              SegmentReason |
+                              UserCancelReason |
+                              SendReason |
+                              OtherReason,
+      TransactionReason    :: megaco_encoder:error_desc(),
+      SegmentReason        :: {megaco_encoder:segment_no(),
+                               LastSegment,
+                               megaco_encoder:error_desc()},
+      OtherReason          :: timeout |
+                              {segment_timeout, MissingSegments} |
+                              exceeded_recv_pending_limit | term(),
+      LastSegment          :: boolean(),
+      MissingSegments      :: [megaco_encoder:segment_no()],
+      UserCancelReason     :: {user_cancel, ReasonForUserCancel},
+      ReasonForUserCancel  :: term(),
+      SendReason           :: SendCancelledReason | SendFailedReason,
+      SendCancelledReason  :: {send_message_cancelled,
+                               ReasonForSendCancel},
+      ReasonForSendCancel  :: term(),
+      SendFailedReason     :: {send_message_failed, ReasonForSendFailure},
+      ReasonForSendFailure :: term(),
+      ReplyNo              :: pos_integer().
+
+
+-callback handle_trans_ack(ConnHandle,
+                           ProtocolVersion,
+                           AckStatus,
+                           AckData) ->
+    ok when
+      ConnHandle           :: conn_handle(),
+      ProtocolVersion      :: megaco_encoder:protocol_version(),
+      AckStatus            :: ok | {error, Reason},
+      AckData              :: term(),
+      Reason               :: UserCancelReason | SendReason | OtherReason,
+      UserCancelReason     :: {user_cancel, ReasonForUserCancel},
+      ReasonForUserCancel  :: term(),
+      SendReason           :: SendCancelledReason | SendFailedReason,
+      SendCancelledReason  :: {send_message_cancelled, ReasonForSendCancel},
+      ReasonForSendCancel  :: term(),
+      SendFailedReason     :: {send_message_failed, ReasonForSendFailure},
+      ReasonForSendFailure :: term(),
+      OtherReason          :: term().
+-callback handle_trans_ack(ConnHandle,
+                           ProtocolVersion,
+                           AckStatus,
+                           AckData,
+                           Extra) ->
+    ok when
+      ConnHandle           :: conn_handle(),
+      ProtocolVersion      :: megaco_encoder:protocol_version(),
+      AckStatus            :: ok | {error, Reason},
+      AckData              :: term(),
+      Extra                :: term(),
+      Reason               :: UserCancelReason | SendReason | OtherReason,
+      UserCancelReason     :: {user_cancel, ReasonForUserCancel},
+      ReasonForUserCancel  :: term(),
+      SendReason           :: SendCancelledReason | SendFailedReason,
+      SendCancelledReason  :: {send_message_cancelled, ReasonForSendCancel},
+      ReasonForSendCancel  :: term(),
+      SendFailedReason     :: {send_message_failed, ReasonForSendFailure},
+      ReasonForSendFailure :: term(),
+      OtherReason          :: term().
+
+-callback handle_unexpected_trans(ConnHandle, ProtocolVersion, Trans) ->
+    ok when
+      ConnHandle      :: conn_handle(),
+      ProtocolVersion :: megaco_encoder:protocol_version(),
+      Trans           :: megaco_encoder:transaction_pending() |
+                         megaco_encoder:transaction_reply() |
+                         megaco_encoder:transaction_response_ack().
+-callback handle_unexpected_trans(ConnHandle, ProtocolVersion, Trans, Extra) ->
+    ok when
+      ConnHandle      :: conn_handle(),
+      ProtocolVersion :: megaco_encoder:protocol_version(),
+      Trans           :: megaco_encoder:transaction_pending() |
+                         megaco_encoder:transaction_reply() |
+                         megaco_encoder:transaction_response_ack(),
+      Extra           :: term().
+
+-callback handle_trans_request_abort(ConnHandle,
+                                     ProtocolVersion,
+                                     TransNo,
+                                     Pid) ->
+    ok when
+      ConnHandle      :: conn_handle(),
+      ProtocolVersion :: megaco_encoder:protocol_version(),
+      TransNo         :: integer(),
+      Pid             :: undefined | pid().
+-callback handle_trans_request_abort(ConnHandle,
+                                     ProtocolVersion,
+                                     TransNo,
+                                     Pid,
+                                     Extra) ->
+    ok when
+      ConnHandle      :: conn_handle(),
+      ProtocolVersion :: megaco_encoder:protocol_version(),
+      TransNo         :: integer(),
+      Pid             :: undefined | pid(),
+      Extra           :: term().
+
+-callback handle_segment_reply(ConnHandle,
+                               ProtocolVersion,
+                               TransNo,
+                               SegNo,
+                               SegCompl) ->
+    ok when
+      ConnHandle      :: conn_handle(),
+      ProtocolVersion :: megaco_encoder:protocol_version(),
+      TransNo         :: integer(),
+      SegNo           :: integer(),
+      SegCompl        :: asn1_NOVALUE | 'NULL'.
+-callback handle_segment_reply(ConnHandle,
+                               ProtocolVersion,
+                               TransNo,
+                               SegNo,
+                               SegCompl,
+                               Extra) ->
+    ok when
+      ConnHandle      :: conn_handle(),
+      ProtocolVersion :: megaco_encoder:protocol_version(),
+      TransNo         :: integer(),
+      SegNo           :: megaco_encoder:segment_no(),
+      SegCompl        :: asn1_NOVALUE | 'NULL',
+      Extra           :: term().
+
+-optional_callbacks(
+   [
+    %% The actual number of arguments to *all* functions,
+    %% depend of the user_args config option.
+    handle_connect/2,
+    handle_connect/3,
+    handle_disconnect/3,
+    handle_syntax_error/3,
+    handle_syntax_error/4,
+    handle_message_error/3,
+    handle_message_error/4,
+    handle_trans_request/3,
+    handle_trans_request/4,
+    handle_trans_long_request/3,
+    handle_trans_long_request/4,
+    handle_trans_reply/4,
+    handle_trans_reply/5,
+    handle_trans_ack/4,
+    handle_trans_ack/5,
+    handle_unexpected_trans/3,
+    handle_unexpected_trans/4,
+    handle_trans_request_abort/4,
+    handle_trans_request_abort/5,
+    handle_segment_reply/5,
+    handle_segment_reply/6
+   ]).
diff --git a/lib/megaco/src/engine/modules.mk b/lib/megaco/src/engine/modules.mk
index b74a096e40..a7f82c1836 100644
--- a/lib/megaco/src/engine/modules.mk
+++ b/lib/megaco/src/engine/modules.mk
@@ -2,7 +2,7 @@
 
 # %CopyrightBegin%
 # 
-# Copyright Ericsson AB 2001-2016. All Rights Reserved.
+# Copyright Ericsson AB 2001-2019. All Rights Reserved.
 # 
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -21,6 +21,7 @@
 BEHAVIOUR_MODULES = \
 	megaco_edist_compress \
 	megaco_encoder \
+	megaco_user \
 	megaco_transport
 
 MODULES = \