ts_protocol.erl

%%%-------------------------------------------------------------------
%% @copyright Process One inc.
%% @author Geoff Cant <nem@erlang.geek.nz>
%% @version 1.0, {@date} {@time}
%% @doc Tsung protocol module behaviour and edoc.
%% @end
%%%-------------------------------------------------------------------
-module(ts_protocol).

-export([init_dynparams/0,
         add_dynparams/4,
         get_message/1,
         session_defaults/0,
         parse/2,
         parse_bidi/2,
         parse_config/2,
         new_session/0
        ]).

%% Behaviour definition
-export([behaviour_info/1]).

%% @hidden
behaviour_info(callbacks) ->
    [{init_dynparams,0},
     {add_dynparams,4},
     {get_message,1},
     {session_defaults,0},
     {parse,2},
     {parse_bidi,2},
     {parse_config,2},
     {new_session,0}];
behaviour_info(_Other) ->
    undefined.

%%====================================================================
%% Data Types
%%====================================================================

%% @type dyndata() = #dyndata{proto=ProtoData::term(),dynvars=list()}.
%%  Dynamic data structure
%% @end

%% @type server() = {Host::tuple(),Port::integer(),Protocol::atom()}.
%%   Host/Port/Protocol tuple
%% @end

%% @type param() = {dyndata(), server()}.
%%  Dynamic data structure
%% @end

%% @type hostdata() = {Host::tuple(),Port::integer()}.
%%  Host/Port pair
%% @end

%% @type client_data() = binary() | closed.
%%  Data passed to a protocol implementation is either a binary or the
%%  atom closed indicating that the server closed the tcp connection.
%% @end

%%====================================================================
%% API
%%====================================================================

%% @spec parse_config(#xmlElement{}, Config::term()) -> NewConfig::term()
%% @doc Parses a tsung.xml configuration file xml element for this
%% protocol and updates the Config term.
%% @end 
parse_config(_Xml,_Config) ->
    erlang:error(dummy_implementation).

%% @spec session_defaults() -> {ok, Persistent} | {ok, Persistent, Bidi}
%%  Persistent = bool()
%%  Bidi = bool()
%% @doc Default parameters for sessions of this protocol. Persistent
%% is true if connections are preserved after the underlying tcp
%% connection closes. Bidi should be true for bidirectional protocols
%% where the protocol module needs to reply to data sent from the
%% server.  @end
session_defaults() ->
    erlang:error(dummy_implementation).

%% @spec new_session() -> State::term()
%% @doc Initialises the state for a new protocol session.
%% @end
new_session() ->
    erlang:error(dummy_implementation).

%% @spec init_dynparams() -> dyndata()
%% @doc Creates a new record/term for storing dynamic request data.
%% @end 
init_dynparams() ->
    erlang:error(dummy_implementation).

%% @spec add_dynparams(Subst, dyndata(), param(), hostdata()) -> {dyndata(), server()} | dyndata()
%%  Subst = term()
%% @doc Updates the dynamic request data structure created by
%% {@link ts_protocol:init_dynparams/0. init_dynparams/0}.
%% @end 
add_dynparams(_Subst, _DynData, _Param, _HostData) ->
    erlang:error(dummy_implementation).

%% @spec parse(Data::client_data(), State) -> {NewState, Opts, Close}
%%  State = #state_rcv{}
%%  Opts = proplist()
%%  Close = bool()
%% @doc 
%%  Opts is a list of inet:setopts socket options. Don't change the
%%  active/passive mode here as tsung will set {active,once} before
%%  your options.
%%  Setting Close to true will cause tsung to close the connection to
%%  the server.
%% @end 
parse(_Data, _State) ->
    erlang:error(dummy_implementation).

%% @spec parse_bidi(Data, State) -> {nodata, NewState} | {Data, NewState}
%%  Data = client_data()
%%  NewState = term()
%%  State = term()
%% @doc Parse a block of data from the server. No reply will be sent
%% if the return value is nodata, otherwise the Data binary will be
%% sent back to the server immediately.
%% @end 
parse_bidi(_Data, _State) ->
    erlang:error(dummy_implementation).

%% @spec get_message(param()) -> Message::binary()
%% @doc Creates a new message to send to the connected server.
%% @end 
get_message(_Param) ->
    erlang:error(dummy_implementation).