Module gen_smsc

Copyright © 2004 Enrique Marcote Peña

• Description
• Function Index
• Function Details

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

Behaviour: gen_server, gen_smsc_session.

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

Description

A generic SMSC 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 SMSC, thus silently dropped if an error occurs. To monitor sessions, SMSC programmers may either use erlang:monitor(process, Session) or explicitly create a link to them.

SMPP operations are directly issued upon sessions, they don't go through the SMSC server loop. This means you may call the functions session_start/2, session_start/3, session_stop/1, alert_notification/2, outbind/2, deliver_sm/2 , data_sm/2 or unbind/1 from within any callback without having the risk of blocking the SMSC server.

Please refer to test_smsc.erl for a minimal SMSC example. There is also a SMSC skeleton you may use as the starting point of your SMSC development, find the module smsc_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 SMSC whenever that particular function is called.

Callback Function Details

init/1

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

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

handle_bind/3

• Bind = {bind_receiver, Session, Pdu} | {bind_transmitter, Session, Pdu} | {bind_transceiver, 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 bind_receiver, bind_transmitter and bind_transceiver operations (from the peer ESMEs) to the callback SMSC.

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

handle_operation/3

• Operation = {broadcast_sm, Session, Pdu} | {cancel_broadcast_sm, Session, Pdu} | {cancel_sm, Session, Pdu} | {query_broadcast_sm, Session, Pdu} | {query_sm, Session, Pdu} | {replace_sm, Session, Pdu} | {submit_multi, Session, Pdu} | {submit_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 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 ESMEs) to the callback SMSC.

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 SMSC 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

• Unbind = {unbind, 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 | {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

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

Notifies listen socket failures to the callback SMSC.

handle_call/3

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

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

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

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

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

Function Details

alert_notification/2

alert_notification(Session, ParamList) -> ok

• Session = pid()
• ParamList = [{ParamName, ParamValue}]
• ParamName = atom()
• ParamValue = term()

Issues an alert_notification operation on the session identified by Session.

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.

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.

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.

deliver_sm/2

deliver_sm(Session, ParamList) -> Result

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

Issues a deliver_sm operation on the session identified by Session.

handle_bind/3

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

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

gen_smsc_session - handle_bind/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(X1::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 = broadcast_sm | cancel_broadcast_sm | cancel_sm | query_broadcast_sm | query_sm | replace_sm | submit_multi | submit_sm | data_sm
• Pdu = pdu()
• Result = {ok, ParamList} | {error, Error, ParamList}
• ParamList = [{ParamName, ParamValue}]
• ParamName = atom()
• ParamValue = term()

gen_smsc_session - handle_operation/3 callback implementation.

handle_unbind/3

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

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

gen_smsc_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, infinity, DEFAULT_SMPP_TIMERS).

Puts the SMSC Server ServerRef to listen on DEFAULT_SMPP_PORT.

By default infinity connections are accepted. 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()
• Timers = timers()
• Count = int() | infinity
• Reason = term()

Puts the SMSC Server ServerRef to listen on Port

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

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

See also: listen_start/1.

listen_stop/1

listen_stop(ServerRef) -> ok

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

Stops listening.

outbind/2

outbind(Session, ParamList) -> ok

• Session = pid()
• ParamList = [{ParamName, ParamValue}]
• ParamName = atom()
• ParamValue = term()

Issues an outbind 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 SMSC.

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

session_start/3

session_start(Address, Port, Timers) -> Result

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

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

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

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

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

session_stop/1

session_stop(Session) -> ok

• Session = pid()

Stops 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 SMSC 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 SMSC 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 SMSC 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 SMSC 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.

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.