Module gen_esme

Generic ESME.

Description
Function Index
Function Details

Version: 1.1, {13 May 2004} 11:56:47.

Behaviour: gen_esme_session, gen_server.

Authors: Enrique Marcote Peña (mpquique_at_users.sourceforge.net) [web site: http://oserl.sourceforge.net/].

Description

Generic ESME.

A generic ESME implemented as a gen_server.

This behaviour acts as an extended gen_server, homonymous functions have the exact same meaning.

By default sessions are NOT linked to the parent ESME, thus silently dropped if an error occurs. To monitor sessions, ESME programmers may either use erlang:monitor(process, Session) or explicitly create a link to them.

SMPP operations are directly issued upon underlying sessions, they don't go through the ESME server loop. This means you may call the functions session_start/2, session_start/3, session_stop/1, bind_receiver/2, bind_transmitter/2, bind_transceiver/2, broadcast_sm/2, cancel_broadcast_sm/2, cancel_sm/2, data_sm/2, query_broadcast_sm/2, query_sm/2, replace_sm/2 , submit_multi/2, submit_sm/2 or unbind/1 from within any callback without having the risk of blocking the ESME server.

Please refer to echo_esme.erl for a minimal ESME example. There is also an ESME skeleton you may use as the starting point of your ESME development, find the module esme_skel.erl under doc/examples directory.

Callback Function Index

A module implementing this behaviour must export these functions. Leaving a callback undefined crashes the entire ESME whenever that particular function is called.

init/1	Forwards gen_server:init/1 callbacks to the ESME server.
handle_outbind/3	Forwards outbind operations (from the peer SMSCs) to the callback ESME.
handle_alert_notification/3	Forwards alert_notification operations (from the peer SMSCs) to the callback ESME.
handle_operation/3	Forwards broadcast_sm, cancel_broadcast_sm, cancel_sm, query_broadcast_sm, query_sm, replace_sm, submit_multi, submit_sm and data_sm operations (from the peer SMSC) to the callback ESME.
handle_unbind/3	This callback forwards an unbind request (issued by peer SMSCs) to the callback ESME.
handle_listen_error/1	Notifies listen socket failures to the callback ESME.
handle_call/3	Forwards gen_server:handle_call/3 callbacks to the ESME server.
handle_cast/2	Forwards gen_server:handle_cast/2 callbacks to the ESME server.	.
handle_info/2	Forwards gen_server:handle_info/2 callbacks to the ESME server.	.
terminate/2	Forwards gen_server:terminate/2 callbacks to the ESME server.	.
code_change/3	Forwards gen_server:code_change/3 callbacks to the ESME server.	.

Callback Function Details

init/1

init(Args) -> Result

Forwards gen_server:init/1 callbacks to the SMSC server.

Refer to OTP gen_server behaviour documentation for greater details on this callback.

handle_outbind/3

handle_outbind(Outbind, From, State) -> Result

OutBind = {outbind, Session, Pdu}
Session = pid()
Pdu = pdu()
From = term()
State = term()
Result = {noreply, NewState} | {noreply, NewState, Timeout} | {stop, Reason, NewState}
ParamList = [{ParamName, ParamValue}]
ParamName = atom()
ParamValue = term()
Timeout = int()
NewState = term()
Reason = term()

Forwards outbind, operations (from the peer SMSCs) to the callback ESME.

handle_alert_notification/3

handle_alert_notification(AlertNotification, From, State) -> Result

AlertNotification = {alert_notification, Session, Pdu}
Session = pid()
Pdu = pdu()
From = term()
State = term()
Result = {noreply, NewState} | {noreply, NewState, Timeout} | {stop, Reason, NewState}
ParamList = [{ParamName, ParamValue}]
ParamName = atom()
ParamValue = term()
Timeout = int()
NewState = term()
Reason = term()

Forwards alert_notification, operations (from the peer SMSCs) to the callback ESME.

handle_operation/3

handle_operation(Operation, From, State) -> Result

Operation = {deliver_sm, Session, Pdu} | {data_sm, Session, Pdu}
Session = pid()
Pdu = pdu()
From = term()
State = term()
Result = {reply, Reply, NewState} | {reply, Reply, NewState, Timeout} | {noreply, NewState} | {noreply, NewState, Timeout} | {stop, Reason, Reply, NewState} | {stop, Reason, NewState}
Reply = {ok, ParamList} | {error, Error, ParamList}
ParamList = [{ParamName, ParamValue}]
ParamName = atom()
ParamValue = term()
Timeout = int()
NewState = term()
Reason = term()

Forwards deliver_sm and data_sm operations (from the peer SMSCs) to the callback ESME.

The ParamList included in the response is used to construct the response PDU. If a command_status other than ESME_ROK is to be returned by the ESME in the response PDU, the callback should return the term {error, Error, ParamList}, where Error is the desired command_status error code.

handle_unbind/3

handle_unbind(Unbind, From, State) -> Result

Unbind = {unbind, Session, Pdu}
Session = pid()
Pdu = pdu()
Result = {reply, Reply, NewState} | {reply, Reply, NewState, Timeout} | {noreply, NewState} | {noreply, NewState, Timeout} | {stop, Reason, Reply, NewState} | {stop, Reason, NewState}
Reply = ok | {error, Error}
Error = int()
Timeout = int()
NewState = term()
Reason = term()

This callback forwards an unbind request (issued by peer ESMEs) to the SMSC.

If ok returned an unbind_resp with a ESME_ROK command_status is sent to the MC and the session moves into the unbound state. When {error, Error} is returned by the ESME, the response PDU sent by the session to the MC will have an Error command_status and the session will remain on it's current bound state (bound_rx, bound_tx or bound_trx).

handle_listen_error/1

handle_listen_error(State) -> Result

State = term()
Result = {noreply, NewState} | {noreply, NewState, Timeout} | {stop, Reason, NewState}
NewState = term()
Reason = term()
Timeout = int()
NewState = term()
Reason = term()

Notifies listen socket failures to the callback SMSC.

handle_call/3

handle_call(Request, From, State) -> Result

Forwards gen_server:handle_call/3 callbacks to the SMSC server.

Refer to OTP gen_server behaviour documentation for greater details on this callback.

handle_cast/2

handle_cast(Request, State) -> Result

Forwards gen_server:handle_cast/2 callback to the SMSC server.

Refer to OTP gen_server behaviour documentation for greater details on this callback.

handle_info/2

handle_info(Info, State) -> Result

Forwards gen_server:handle_info/2 callback to the SMSC server.

Refer to OTP gen_server behaviour documentation for greater details on this callback.

terminate/2

terminate(Reason, State)

Forwards gen_server:terminate/2 callback to the SMSC server.

Refer to OTP gen_server behaviour documentation for greater details on this callback.

code_change/3

code_change(OldVsn, State, Extra) -> {ok, NewState}

Forwards gen_server:code_change/3 callback to the SMSC server.

Refer to OTP gen_server behaviour documentation for greater details on this callback.

Function Index

behaviour_info/1	Gives information about the behaviour.
bind_receiver/2	Issues a bind_receiver operation on the session identified by `Session`.
bind_transceiver/2	Issues a bind_transceiver operation on the session identified by `Session`.
bind_transmitter/2	Issues a bind_transmitter operation on the session identified by `Session`.
broadcast_sm/2	Issues a broadcast_sm operation on the session identified by `Session`.
call/2	Equivalent to gen_server:call/2.
call/3	Equivalent to gen_server:call/3.
cancel_broadcast_sm/2	Issues a cancel_broadcast_sm operation on the session identified by `Session`.
cancel_sm/2	Issues a cancel_sm operation on the session identified by `Session`.
cast/2	Equivalent to gen_server:cast/2.
code_change/3	gen_server - code_change/3 callback implementation.
data_sm/2	Issues a data_sm operation on the session identified by `Session`.
handle_alert_notification/3	gen_esme_session - handle_alert_notification/3 callback implementation.
handle_call/3	gen_server - handle_call/3 callback implementation.
handle_cast/2	gen_server - handle_cast/2 callback implementation.
handle_info/2	gen_server - handle_info/2 callback implementation.
handle_operation/3	gen_esme_session - handle_operation/3 callback implementation.
handle_outbind/3	gen_esme_session - handle_outbind/3 callback implementation.
handle_unbind/3	gen_esme_session - handle_unbind/3 callback implementation.
init/1	gen_server - init/1 callback implementation.
listen_start/1	Puts the ESME Server `ServerRef` to listen on `DEFAULT_SMPP_PORT`.
listen_start/4	Puts the ESME Server `ServerRef` to listen on `Port` `Timers` is a `timers` record as declared in oserl.hrl. Accepted session will be subject to given timers. `Count` connections are accepted. Started sessions are NOT linked to the SMSC.
listen_stop/1	Stops listening.
query_broadcast_sm/2	Issues a query_broadcast_sm operation on the session identified by `Session`.
query_sm/2	Issues a query_sm operation on the session identified by `Session`.
replace_sm/2	Issues a replace_sm operation on the session identified by `Session`.
reply/2	Equivalent to gen_server:reply/2.
session_start/2	Opens a new session.
session_start/3	Opens a new session.
session_stop/1	Closes the `Session`.
start/3	Starts the ESME server.
start/4	Starts the ESME server.
start_link/3	Starts the ESME server.
start_link/4	Starts the ESME server.
submit_multi/2	Issues a submit_multi operation on the session identified by `Session`.
submit_sm/2	Issues a submit_sm operation on the session identified by `Session`.
terminate/2	gen_server - terminate/2 callback implementation.
unbind/1	Issues an unbind operation on the session identified by `Session`.

Function Details

behaviour_info/1

behaviour_info(Other::Category) -> Info

Category = callbacks | term()
Info = CallbacksInfo | term()
CallbacksInfo = [{FunctionName, Arity}]
FunctionName = atom()
Arity = int()

Gives information about the behaviour.

bind_receiver/2

bind_receiver(Session, ParamList) -> Result

Session = pid()
ParamList = [{ParamName, ParamValue}]
ParamName = atom()
ParamValue = term()
Result = {ok, PduResp} | {error, Error}
PduResp = pdu()
Error = int()

Issues a bind_receiver operation on the session identified by Session.

bind_transceiver/2

bind_transceiver(Session, ParamList) -> Result

Session = pid()
ParamList = [{ParamName, ParamValue}]
ParamName = atom()
ParamValue = term()
Result = {ok, PduResp} | {error, Error}
PduResp = pdu()
Error = int()

Issues a bind_transceiver operation on the session identified by Session.

bind_transmitter/2

bind_transmitter(Session, ParamList) -> Result

Session = pid()
ParamList = [{ParamName, ParamValue}]
ParamName = atom()
ParamValue = term()
Result = {ok, PduResp} | {error, Error}
PduResp = pdu()
Error = int()

Issues a bind_transmitter operation on the session identified by Session.

broadcast_sm/2

broadcast_sm(Session, ParamList) -> Result

Session = pid()
ParamList = [{ParamName, ParamValue}]
ParamName = atom()
ParamValue = term()
Result = {ok, PduResp} | {error, Error}
PduResp = pdu()
Error = int()

Issues a broadcast_sm operation on the session identified by Session.

call/2

call(ServerRef, Request) -> Reply

ServerRef = Name | {Name, Node} | {global, Name} | pid()
Name = atom()
Node = atom()
Request = term()
Reply = term()

Equivalent to gen_server:call/2.

Request is an arbitrary term which is passed as one of the arguments to Module:handle_call/3.

Please refer to the gen_server man page for greater details.

call/3

call(ServerRef, Request, Timeout) -> Reply

ServerRef = Name | {Name, Node} | {global, Name} | pid()
Name = atom()
Node = atom()
Request = term()
Timeout = int() | infinity
Reply = term()

Equivalent to gen_server:call/3.

Request is an arbitrary term which is passed as one of the arguments to Module:handle_call/3.

Please refer to the gen_server man page for greater details.

cancel_broadcast_sm/2

cancel_broadcast_sm(Session, ParamList) -> Result

Session = pid()
ParamList = [{ParamName, ParamValue}]
ParamName = atom()
ParamValue = term()
Result = {ok, PduResp} | {error, Error}
PduResp = pdu()
Error = int()

Issues a cancel_broadcast_sm operation on the session identified by Session.

cancel_sm/2

cancel_sm(Session, ParamList) -> Result

Session = pid()
ParamList = [{ParamName, ParamValue}]
ParamName = atom()
ParamValue = term()
Result = {ok, PduResp} | {error, Error}
PduResp = pdu()
Error = int()

Issues a cancel_sm operation on the session identified by Session.

cast/2

cast(ServerRef, Request) -> Reply

ServerRef = Name | {Name, Node} | {global, Name} | pid()
Name = atom()
Node = atom()
Request = term()
Reply = term()

Equivalent to gen_server:cast/2.

Request is an arbitrary term which is passed as one of the arguments to Module:handle_cast/2.

Please refer to the gen_server man page for greater details.

code_change/3

code_change(OldVsn, S::State, Extra) -> {ok, NewState}

OldVsn = undefined | term()
State = term()
Extra = term
NewState = term()

gen_server - code_change/3 callback implementation.

Convert process state when code is changed.

data_sm/2

data_sm(Session, ParamList) -> Result

Session = pid()
ParamList = [{ParamName, ParamValue}]
ParamName = atom()
ParamValue = term()
Result = {ok, PduResp} | {error, Error}
PduResp = pdu()
Error = int()

Issues a data_sm operation on the session identified by Session.

handle_alert_notification/3

handle_alert_notification(ServerRef, Session, Pdu) -> ok

ServerRef = pid()
Session = pid()
Pdu = pdu()

gen_esme_session - handle_alert_notification/3 callback implementation.

handle_call/3

handle_call(R::Request, From, S::State) -> Result

Request = term()
From = {pid(), Tag}
State = term()
Result = {reply, Reply, NewState} | {reply, Reply, NewState, Timeout} | {noreply, NewState} | {noreply, NewState, Timeout} | {stop, Reason, Reply, NewState} | {stop, Reason, NewState}
Reply = term()
NewState = term()
Timeout = int() | infinity
Reason = term()

gen_server - handle_call/3 callback implementation.

Handling call messages.

On {stop, Reason, Reply, NewState} terminate/2 is called
On {stop, Reason, NewState} terminate/2 is called

See also: terminate/2.

handle_cast/2

handle_cast(R::Request, S::State) -> Result

Request = term()
Result = {noreply, NewState} | {noreply, NewState, Timeout} | {stop, Reason, NewState}
NewState = term()
Timeout = int() | infinity
Reason = normal | term()

gen_server - handle_cast/2 callback implementation.

Handling cast messages.

On {stop, Reason, State} terminate/2 is called

See also: terminate/2.

handle_info/2

handle_info(Info, S::State) -> Result

Info = timeout | term()
State = term()
Result = {noreply, NewState} | {noreply, NewState, Timeout} | {stop, Reason, NewState}
NewState = term()
Timeout = int() | infinity
Reason = normal | term()

gen_server - handle_info/2 callback implementation.

Handling all non call/cast messages.

On {stop, Reason, State} terminate/2 is called.

See also: terminate/2.

handle_operation/3

handle_operation(ServerRef, Session, X3::{CmdName, Pdu}) -> Result

ServerRef = pid()
Session = pid()
CmdName = data_sm | deliver_sm
Pdu = pdu()
Result = {ok, ParamList} | {error, Error, ParamList}
ParamList = [{ParamName, ParamValue}]
ParamName = atom()
ParamValue = term()

gen_esme_session - handle_operation/3 callback implementation.

handle_outbind/3

handle_outbind(ServerRef, Session, Pdu) -> ok

ServerRef = pid()
Session = pid()
Pdu = pdu()

gen_esme_session - handle_outbind/3 callback implementation.

handle_unbind/3

handle_unbind(ServerRef, Session, Pdu) -> ok | {error, Error}

ServerRef = pid()
Session = pid()
Pdu = pdu()
Error = int()

gen_esme_session - handle_unbind/3 callback implementation.

init/1

init(X1::Args) -> Result

Args = term()
Result = {ok, State} | {ok, State, Timeout} | ignore | {stop, Reason}
State = term()
Timeout = int() | infinity
Reason = term()

gen_server - init/1 callback implementation.

Initiates the server.

listen_start/1

listen_start(ServerRef) -> ok | {error, Reason}

ServerRef = Name | {Name, Node} | {global, Name} | pid()
Name = atom()
Node = atom()
Reason = term()

Equivalent to listen(ServerRef, DEFAULT_SMPP_PORT, 1, DEFAULT_SMPP_TIMERS).

Puts the ESME Server ServerRef to listen on DEFAULT_SMPP_PORT.

By default only one connection is accepted before the listen socket is closed. Started sessions are NOT linked to the SMSC.

See also: listen_start/4.

listen_start/4

listen_start(ServerRef, Port, Count, Timers) -> ok | {error, Reason}

ServerRef = Name | {Name, Node} | {global, Name} | pid()
Name = atom()
Node = atom()
Port = int()
Count = int() | infinity
Timers = timers()
Reason = term()

Puts the ESME Server ServerRef to listen on Port

Timers is a timers record as declared in oserl.hrl. Accepted session will be subject to given timers.

Count connections are accepted. Started sessions are NOT linked to the SMSC.

listen_stop/1

listen_stop(ServerRef) -> ok

ServerRef = Name | {Name, Node} | {global, Name} | pid()
Name = atom()
Node = atom()

Stops listening.

query_broadcast_sm/2

query_broadcast_sm(Session, ParamList) -> Result

Session = pid()
ParamList = [{ParamName, ParamValue}]
ParamName = atom()
ParamValue = term()
Result = {ok, PduResp} | {error, Error}
PduResp = pdu()
Error = int()

Issues a query_broadcast_sm operation on the session identified by Session.

query_sm/2

query_sm(Session, ParamList) -> Result

Session = pid()
ParamList = [{ParamName, ParamValue}]
ParamName = atom()
ParamValue = term()
Result = {ok, PduResp} | {error, Error}
PduResp = pdu()
Error = int()

Issues a query_sm operation on the session identified by Session.

replace_sm/2

replace_sm(Session, ParamList) -> Result

Session = pid()
ParamList = [{ParamName, ParamValue}]
ParamName = atom()
ParamValue = term()
Result = {ok, PduResp} | {error, Error}
PduResp = pdu()
Error = int()

Issues a replace_sm operation on the session identified by Session.

reply/2

reply(Client, Reply) -> true

Client = term()
Reply = term()

Equivalent to gen_server:reply/2.

Please refer to the gen_server man page for greater details.

session_start/2

session_start(Address, Port) -> Result

Address = string() | atom() | ip_address()
Port = int()
Result = {ok, Session} | {error, Reason}
Session = pid()
Reason = term()

Equivalent to session_start(Address, Port, DEFAULT_SMPP_TIMERS).

Opens a new session. By default Sessions are NOT linked to the ESME.

Returns {ok, Session} if success, {error, Reason} otherwise.

session_start/3

session_start(Address, Port, Timers) -> Result

Address = string() | atom() | ip_address()
Port = int()
Result = {ok, Session} | {error, Reason}
Session = pid()
Reason = term()

Opens a new session. By default Sessions are NOT linked to the ESME.

Timers is a timers record as declared in oserl.hrl.

Returns {ok, Session} if success, {error, Reason} otherwise.

See also: session_start/2, gen_esme_session:start/3.

session_stop/1

session_stop(Session) -> ok

Session = pid()

Closes the Session.

start/3

start(Module, Args, Options) -> Result

Module = atom()
Result = {ok, Pid} | ignore | {error, Error}
Pid = pid()
Error = {already_started, Pid} | term()

Starts the ESME server.

Module, Args and Options have the exact same meaning as in gen_server behavior.

See also: start/4, start_link/3, gen_server:start/3.

start/4

start(ServerName, Module, Args, Options) -> Result

ServerName = {local, Name} | {global, Name}
Name = atom()
Module = atom()
Result = {ok, Pid} | ignore | {error, Error}
Pid = pid()
Error = {already_started, Pid} | term()

Starts the ESME server.

ServerName, Module, Args and Options have the exact same meaning as in gen_server behavior.

See also: start/3, start_link/4, gen_server:start/4.

start_link/3

start_link(Module, Args, Options) -> Result

Module = atom()
Result = {ok, Pid} | ignore | {error, Error}
Pid = pid()
Error = {already_started, Pid} | term()

Starts the ESME server.

Module, Args and Options have the exact same meaning as in gen_server behavior.

See also: start/3, start_link/4, gen_server:start_link/3.

start_link/4

start_link(ServerName, Module, Args, Options) -> Result

ServerName = {local, Name} | {global, Name}
Name = atom()
Module = atom()
Result = {ok, Pid} | ignore | {error, Error}
Pid = pid()
Error = {already_started, Pid} | term()

Starts the ESME server.

ServerName, Module, Args and Options have the exact same meaning as in gen_server behavior.

See also: start/4, start_link/3, gen_server:start_link/4.

submit_multi/2

submit_multi(Session, ParamList) -> Result

Session = pid()
ParamList = [{ParamName, ParamValue}]
ParamName = atom()
ParamValue = term()
Result = {ok, PduResp} | {error, Error}
PduResp = pdu()
Error = int()

Issues a submit_multi operation on the session identified by Session.

submit_sm/2

submit_sm(Session, ParamList) -> Result

Session = pid()
ParamList = [{ParamName, ParamValue}]
ParamName = atom()
ParamValue = term()
Result = {ok, PduResp} | {error, Error}
PduResp = pdu()
Error = int()

Issues a submit_sm operation on the session identified by Session.

terminate/2

terminate(R::Reason, S::State) -> ok

Reason = normal | shutdown | term()
State = term()

gen_server - terminate/2 callback implementation.

Shutdown the server.

Return value is ignored by gen_server.

unbind/1

unbind(Session) -> Result

Session = pid()
Result = {ok, PduResp} | {error, Error}
PduResp = pdu()
Error = int()

Issues an unbind operation on the session identified by Session.