%%
%% %CopyrightBegin%
%%
%% Copyright Ericsson AB 2010-2011. All Rights Reserved.
%%
%% The contents of this file are subject to the Erlang Public License,
%% Version 1.1, (the "License"); you may not use this file except in
%% compliance with the License. You should have received a copy of the
%% Erlang Public License along with this software. If not, it can be
%% retrieved online at http://www.erlang.org/.
%%
%% Software distributed under the License is distributed on an "AS IS"
%% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
%% the License for the specific language governing rights and limitations
%% under the License.
%%
%% %CopyrightEnd%
%%

%%
%% A diameter callback module that can redirect selected callbacks,
%% providing reasonable default implementations otherwise.
%%
%% To order alternate callbacks, configure a #diameter_callback record
%% as the Diameter application callback in question. The record has
%% one field for each callback function as well as 'default' and
%% 'extra' fields. A function-specific field can be set to a
%% diameter:evaluable() in order to redirect the callback
%% corresponding to that field, or to 'false' to request the default
%% callback implemented in this module. If neither of these fields are
%% set then the 'default' field determines the form of the callback: a
%% module name results in the usual callback as if the module had been
%% configured directly as the callback module, a diameter_evaluable()
%% in a callback applied to the atom-valued callback name and argument
%% list. For all callbacks not to this module, the 'extra' field is a
%% list of additional arguments, following arguments supplied by
%% diameter but preceeding those of the diameter:evaluable() being
%% applied.
%%
%% For example, the following config to diameter:start_service/2, in
%% an 'application' tuple, would result in only a mymod:peer_down/3
%% callback, this module implementing the remaining callbacks.
%%
%%   {module, #diameter_callback{peer_down = {mymod, down, []}}}
%%
%% Equivalently, this can also be specified with a [Mod | Args]
%% field/value list as follows.
%%
%%   {module, [diameter_callback, {peer_down, {mymod, down, []}}]}
%%
%% The following would result in this module suppying peer_up and
%% peer_down callback, others taking place in module mymod.
%%
%%   {module, #diameter_callback{peer_up = false,
%%                               peer_down = false,
%%                               default = mymod}}
%%
%% The following would result in all callbacks taking place as
%% calls to mymod:diameter/2.
%%
%%   {module, #diameter_callback{default = {mymod, diameter, []}}}
%%
%% The following are equivalent and result in all callbacks being
%% provided by this module.
%%
%%   {module, #diameter_callback{}}
%%   {module, diameter_callback}
%%

-module(diameter_callback).

%% Default callbacks when no aleternate is specified.
-export([peer_up/3,
         peer_down/3,
         pick_peer/4,
         prepare_request/3,
         prepare_retransmit/3,
         handle_request/3,
         handle_answer/4,
         handle_error/4]).

%% Callbacks taking a #diameter_callback record.
-export([peer_up/4,
         peer_down/4,
         pick_peer/5,
         prepare_request/4,
         prepare_retransmit/4,
         handle_request/4,
         handle_answer/5,
         handle_error/5]).

-include_lib("diameter/include/diameter.hrl").

%%% ----------------------------------------------------------
%%% # peer_up/3
%%% ----------------------------------------------------------

peer_up(_Svc, _Peer, State) ->
    State.

peer_up(Svc, Peer, State, D) ->
    cb(peer_up,
       [Svc, Peer, State],
       D#diameter_callback.peer_up,
       D).

%%% ----------------------------------------------------------
%%% # peer_down/3
%%% ----------------------------------------------------------

peer_down(_Svc, _Peer, State) ->
    State.

peer_down(Svc, Peer, State, D) ->
    cb(peer_down,
       [Svc, Peer, State],
       D#diameter_callback.peer_down,
       D).

%%% ----------------------------------------------------------
%%% # pick_peer/4
%%% ----------------------------------------------------------

pick_peer([Peer|_], _, _Svc, _State) ->
    {ok, Peer};
pick_peer([], _, _Svc, _State) ->
    false.

pick_peer(PeersL, PeersR, Svc, State, D) ->
    cb(pick_peer,
       [PeersL, PeersR, Svc, State],
       D#diameter_callback.pick_peer,
       D).

%%% ----------------------------------------------------------
%%% # prepare_request/3
%%% ----------------------------------------------------------

prepare_request(Pkt, _Svc, _Peer) ->
    {send, Pkt}.

prepare_request(Pkt, Svc, Peer, D) ->
    cb(prepare_request,
       [Pkt, Svc, Peer],
       D#diameter_callback.prepare_request,
       D).

%%% ----------------------------------------------------------
%%% # prepare_retransmit/3
%%% ----------------------------------------------------------

prepare_retransmit(Pkt, _Svc, _Peer) ->
    {send, Pkt}.

prepare_retransmit(Pkt, Svc, Peer, D) ->
    cb(prepare_retransmit,
       [Pkt, Svc, Peer],
       D#diameter_callback.prepare_retransmit,
       D).

%%% ----------------------------------------------------------
%%% # handle_request/3
%%% ----------------------------------------------------------

handle_request(_Pkt, _Svc, _Peer) ->
    {protocol_error, 3001}.  %% DIAMETER_COMMAND_UNSUPPORTED

handle_request(Pkt, Svc, Peer, D) ->
    cb(handle_request,
       [Pkt, Svc, Peer],
       D#diameter_callback.handle_request,
       D).

%%% ----------------------------------------------------------
%%% # handle_answer/4
%%% ----------------------------------------------------------

handle_answer(#diameter_packet{msg = Ans, errors = []}, _Req, _Svc, _Peer) ->
    Ans;
handle_answer(#diameter_packet{msg = Ans, errors = Es}, _Req, _Svc, _Peer) ->
    [Ans | Es].

handle_answer(Pkt, Req, Svc, Peer, D) ->
    cb(handle_answer,
       [Pkt, Req, Svc, Peer],
       D#diameter_callback.handle_answer,
       D).

%%% ---------------------------------------------------------------------------
%%% # handle_error/4
%%% ---------------------------------------------------------------------------

handle_error(Reason, _Req, _Svc, _Peer) ->
    {error, Reason}.

handle_error(Reason, Req, Svc, Peer, D) ->
    cb(handle_error,
       [Reason, Req, Svc, Peer],
       D#diameter_callback.handle_error,
       D).

%% ===========================================================================

%% cb/4

%% Unspecified callback: use default field to determine something
%% appropriate.
cb(CB, Args, undefined, D) ->
    cb(CB, Args, D);

%% Explicitly requested default.
cb(CB, Args, false, _) ->
    apply(?MODULE, CB, Args);

%% A specified callback.
cb(_, Args, F, #diameter_callback{extra = X}) ->
    diameter_lib:eval([[F|X] | Args]).

%% cb/3

%% No user-supplied default: call ours.
cb(CB, Args, #diameter_callback{default = undefined}) ->
    apply(?MODULE, CB, Args);

%% Default is a module name: make the usual callback.
cb(CB, Args, #diameter_callback{default = M,
                                extra = X})
  when is_atom(M) ->
    apply(M, CB, Args ++ X);

%% Default is something else: apply if to callback name and arguments.
cb(CB, Args, #diameter_callback{default = F,
                                extra = X}) ->
    diameter_lib:eval([F, CB, Args | X]).