Module gen_smsc_session

Copyright © 2004 Enrique Marcote Peña

• Description
• Function Index
• Function Details

Version: 1.1, {07 June 2004} 11:56:47.

Behaviour: gen_fsm.

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

Description

A generic SMSC SMPP session modeled as a FSM. It also implements the gen_connection behaviour.

Every SMPP session works over a single TCP/IP connection. If the underlying connection exits, the session is also terminated.

Session failures due to connection errors must be handled by the callback SMSC.

State transitions table

To a better understanding of this behaviour, should notice that the state name on a SMSC session references that state of the ESME session on the other peer. Thus:

bound_rx:

A SMSC session has this state whenever there's a receiver ESME on the other peer.

bound_tx:

If there is a transmitter ESME on the other peer.

bound_trx:

Bound to a transceiver.

Possible states for the SMSC SMPP session are shown in the first row. Events are those in the first column. This table shows the next state given an event and the current state.

Operations issued by the other peer (ESME) are treated asynchronously by the SMSC session, thus represented by async events.

response_timer

One instance of this timer is started for each request. On expiration, the request is considered unsuccessful.

The timer associated to a request is stopped when the corresponding response arrives.

Callback Function Index

A module implementing this behaviour must export these functions. Leaving a callback undefined crashes the entire session (when that particular function is called).

Callback Function Details

handle_bind/3

• SMSC = 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()

Forwards bind_receiver, bind_transmitter and bind_transceiver operations (from the peer ESME) 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 ESME in the response PDU, the callback should return the term {error, Error, ParamList}, where Error is the desired command_status error code.

SMSC is the SMSC's process id, Session is the session id.

handle_operation/3

• SMSC = 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()

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 ESME) 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 ESME in the response PDU, the callback should return the term {error, Error, ParamList}, where Error is the desired command_status error code.

SMSC is the SMSC's process id, Session is the session id.

handle_unbind/3

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

This callback forwards an unbind request (issued by a peer ESME) 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).

SMSC is the SMSC's process id, Session is the session id.

Function Index

Function Details

alert_notification/2

alert_notification(FsmRef, ParamList) -> Result

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

Issues an alert_notification operation on the session identified by FsmRef.

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.

bound_rx/2

bound_rx(R::Event, S::StateData) -> Result

• Event = timeout | term()
• StateData = term()
• Result = {next_state, NextStateName, NextStateData} | {next_state, NextStateName, NextStateData, Timeout} | {stop, Reason, NewStateData}
• NextStateName = atom()
• NextStateData = term()
• Timeout = int() | infinity
• Reason = term()

gen_fsm - StateName/2 callback implementation. Handles async events for the state name bound_rx. Bound against a receiver ESME.

PDUs comming from the other peer (ESME) are received asynchronously.

bound_rx/3

bound_rx(Event, From, S::StateData) -> Result

• Event = term()
• From = {pid(), Tag}
• StateData = term()
• Result = {next_state, NextStateName, NextStateData} | {next_state, NextStateName, NextStateData, Timeout} | {reply, Reply, NextStateName, NextStateData} | {reply, Reply, NextStateName, NextStateData, Timeout} | {stop, Reason, NewStateData} | {stop, Reason, Reply, NewStateData}
• Reply = term()
• NextStateName = atom()
• NextStateData = term()
• Timeout = int() | infinity
• Reason = term()

gen_fsm - StateName/3 callback implementation. Handles events for the state name bound_rx. Bound against a receiver ESME.

bound_trx/2

bound_trx(R::Event, S::StateData) -> Result

• Event = timeout | term()
• StateData = term()
• Result = {next_state, NextStateName, NextStateData} | {next_state, NextStateName, NextStateData, Timeout} | {stop, Reason, NewStateData}
• NextStateName = atom()
• NextStateData = term()
• Timeout = int() | infinity
• Reason = term()

gen_fsm - StateName/2 callback implementation. Handles async events for the state name bound_trx. Bound against a transceiver ESME.

PDUs comming from the other peer (ESME) are received asynchronously.

bound_trx/3

bound_trx(Event, From, S::StateData) -> Result

• Event = term()
• From = {pid(), Tag}
• StateData = term()
• Result = {next_state, NextStateName, NextStateData} | {next_state, NextStateName, NextStateData, Timeout} | {reply, Reply, NextStateName, NextStateData} | {reply, Reply, NextStateName, NextStateData, Timeout} | {stop, Reason, NewStateData} | {stop, Reason, Reply, NewStateData}
• Reply = term()
• NextStateName = atom()
• NextStateData = term()
• Timeout = int() | infinity
• Reason = term()

gen_fsm - StateName/3 callback implementation. Handles events for the state name bound_trx. Bound against a transceiver ESME.

bound_tx/2

bound_tx(R::Event, S::StateData) -> Result

• Event = timeout | term()
• StateData = term()
• Result = {next_state, NextStateName, NextStateData} | {next_state, NextStateName, NextStateData, Timeout} | {stop, Reason, NewStateData}
• NextStateName = atom()
• NextStateData = term()
• Timeout = int() | infinity
• Reason = term()

gen_fsm - StateName/2 callback implementation. Handles async events for the state name bound_tx. Bound against a transmitter ESME.

PDUs comming from the other peer (ESME) are received asynchronously.

bound_tx/3

bound_tx(Event, From, S::StateData) -> Result

• Event = term()
• From = {pid(), Tag}
• StateData = term()
• Result = {next_state, NextStateName, NextStateData} | {next_state, NextStateName, NextStateData, Timeout} | {reply, Reply, NextStateName, NextStateData} | {reply, Reply, NextStateName, NextStateData, Timeout} | {stop, Reason, NewStateData} | {stop, Reason, Reply, NewStateData}
• Reply = term()
• NextStateName = atom()
• NextStateData = term()
• Timeout = int() | infinity
• Reason = term()

gen_fsm - StateName/3 callback implementation. Handles events for the state name bound_tx. Bound against a transmitter ESME.

code_change/4

code_change(OldVsn, StateName, StateData, Extra) -> Result

• OldVsn = undefined | term()
• StateName = term()
• StateData = term()
• Extra = term()
• Result = {ok, NextStateName, NewStateData}
• NextStateName = atom()
• NewStateData = term()

gen_fsm - code_change/4 callback implementation. Convert process state when code is changed

data_sm/2

data_sm(FsmRef, ParamList) -> Result

• FsmRef = Name | {Name, Node} | {global, Name} | 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 FsmRef.

deliver_sm/2

deliver_sm(FsmRef, ParamList) -> Result

• FsmRef = Name | {Name, Node} | {global, Name} | 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 FsmRef.

handle_event/3

handle_event(R::Event, StateName, StateData) -> Result

• Event = die | term()
• StateName = atom()
• StateData = term()
• Result = {next_state, NextStateName, NextStateData} | {next_state, NextStateName, NextStateData, Timeout} | {stop, Reason, NewStateData}
• NextStateName = atom()
• NextStateData = term()
• Timeout = int() | infinity
• Reason = term()

gen_fsm - handle_event/3 callback implementation. Handles events received by gen_fsm:send_all_state_event/2.

handle_info/3

handle_info(Info, StateName, StateData) -> Result

• Info = term()
• StateName = atom()
• StateData = term()
• Result = {next_state, NextStateName, NextStateData} | {next_state, NextStateName, NextStateData, Timeout} | {stop, Reason, NewStateData}
• NextStateName = atom()
• NextStateData = term()
• Timeout = int() | infinity
• Reason = term()

gen_fsm - handle_info/3 callback implementation. Call on reception of any other messages than a synchronous or asynchronous event.

handle_sync_event/4

handle_sync_event(Event, From, StateName, StateData) -> Result

• Event = term()
• From = {pid(), Tag}
• StateName = atom()
• StateData = term()
• Result = {next_state, NextStateName, NextStateData} | {next_state, NextStateName, NextStateData, Timeout} | {reply, Reply, NextStateName, NextStateData} | {reply, Reply, NextStateName, NextStateData, Timeout} | {stop, Reason, NewStateData} | {stop, Reason, Reply, NewStateData}
• Reply = term()
• NextStateName = atom()
• NextStateData = term()
• Timeout = int() | infinity
• Reason = term()

gen_fsm - handle_sync_event/4 callback implementation. Handles events received via gen_fsm:sync_send_all_state_event/2,3.

init/1

init(X1::Args) -> Result

• Args = term()
• Result = {ok, StateName, StateData} | {ok, StateName, StateData, Timeout} | ignore | {stop, StopReason}
• StateName = atom()
• StateData = term()
• Timeout = int()
• StopReason = term()

gen_fsm - init/1 callback implementation. Initializes the the fsm.

open/2

open(R::Event, S::StateData) -> Result

• Event = timeout | term()
• StateData = term()
• Result = {next_state, NextStateName, NextStateData} | {next_state, NextStateName, NextStateData, Timeout} | {stop, Reason, NewStateData}
• NextStateName = atom()
• NextStateData = term()
• Timeout = int() | infinity
• Reason = term()

gen_fsm - StateName/2 callback implementation. Handles async events for the state name open.

PDUs comming from the other peer (ESME) are received asynchronously.

open/3

open(Event, From, S::StateData) -> Result

• Event = term()
• From = {pid(), Tag}
• StateData = term()
• Result = {next_state, NextStateName, NextStateData} | {next_state, NextStateName, NextStateData, Timeout} | {reply, Reply, NextStateName, NextStateData} | {reply, Reply, NextStateName, NextStateData, Timeout} | {stop, Reason, NewStateData} | {stop, Reason, Reply, NewStateData}
• Reply = term()
• NextStateName = atom()
• NextStateData = term()
• Timeout = int() | infinity
• Reason = term()

gen_fsm - StateName/3 callback implementation. Handles events for the state name open.

outbind/2

outbind(FsmRef, ParamList) -> Result

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

Issues an outbind operation on the session identified by FsmRef.

outbound/2

outbound(R::Event, S) -> Result

• Event = timeout | term()
• StateData = term()
• Result = {next_state, NextStateName, NextStateData} | {next_state, NextStateName, NextStateData, Timeout} | {stop, Reason, NewStateData}
• NextStateName = atom()
• NextStateData = term()
• Timeout = int() | infinity
• Reason = term()

gen_fsm - StateName/2 callback implementation. Handles async events for the state name outbound.

PDUs comming from the other peer (ESME) are received asynchronously.

outbound/3

outbound(Event, From, S::StateData) -> Result

• Event = term()
• From = {pid(), Tag}
• StateData = term()
• Result = {next_state, NextStateName, NextStateData} | {next_state, NextStateName, NextStateData, Timeout} | {reply, Reply, NextStateName, NextStateData} | {reply, Reply, NextStateName, NextStateData, Timeout} | {stop, Reason, NewStateData} | {stop, Reason, Reply, NewStateData}
• Reply = term()
• NextStateName = atom()
• NextStateData = term()
• Timeout = int() | infinity
• Reason = term()

gen_fsm - StateName/3 callback implementation. Handles events for the state name outbound.

start/3

start(Mod, Socket, Timers) -> Result

• Mod = atom()
• Socket = socket()
• Timers = timers()
• Result = {ok, Pid} | ignore | {error, Error}
• Pid = pid()
• Error = {already_started, Pid} | term()

Starts the server setting self() as the session SMSC (owner).

Timers is a timers record. Use the macro ?DEFAULT_TIMERS to set the default values.

Refer to oserl.hrl for more details on the timers record definition.

The gen_smsc_session is not registered.

See also: start_link/3, gen_fsm:start/3.

start/4

start(Name, Mod, Socket, Timers) -> Result

• Name = {local, Name} | {global, Name}
• Name = atom()
• Mod = atom()
• Socket = pid()
• Timers = timers()
• Result = {ok, Pid} | ignore | {error, Error}
• Pid = pid()
• Error = {already_started, Pid} | term()

Starts the server setting self() as the session SMSC (owner).

Timers is a timers record. Use the macro ?DEFAULT_TIMERS to set the default values.

Refer to oserl.hrl for more details on the timers record definition.

If Name = {local, TheName}, the gen_smsc_session is registered locally as TheName. If Name = {global, TheName}, the gen_smsc_session is registered globally as TheName.

See also: start_link/4, gen_fsm:start/4.

start_link/3

start_link(Mod, Socket, Timers) -> Result

• Mod = atom()
• Socket = socket()
• Timers = timers()
• Result = {ok, Pid} | ignore | {error, Error}
• Pid = pid()
• Error = {already_started, Pid} | term()

Starts the server setting self() as the session SMSC (owner).

Timers is a timers record. Use the macro ?DEFAULT_TIMERS to set the default values.

Refer to oserl.hrl for more details on the timers record definition.

The gen_smsc_session is not registered.

See also: start/3, gen_fsm:start_link/3.

start_link/4

start_link(Name, Mod, Socket, Timers) -> Result

• Name = {local, Name} | {global, Name}
• Name = atom()
• Mod = atom()
• Socket = pid()
• Timers = timers()
• Result = {ok, Pid} | ignore | {error, Error}
• Pid = pid()
• Error = {already_started, Pid} | term()

Starts the server setting self() as the session SMSC (owner).

Timers is a timers record. Use the macro ?DEFAULT_TIMERS to set the default values.

Refer to oserl.hrl for more details on the timers record definition.

If Name = {local, TheName}, the gen_smsc_session is registered locally as TheName. If Name = {global, TheName}, the gen_smsc_session is registered globally as TheName.

See also: start/4, gen_fsm:start_link/4.

stop/1

stop(FsmRef) -> ok

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

Equivalent to gen_fsm:send_all_state_event(FsmRef, die).

Stops the fsm. This function does *NOT* issue an unbind operation. The unbind must have been previously sent using the unbind/1 function.

See also: gen_fsm:send_all_state_event/2.

terminate/3

terminate(R::Reason, N::StateName, S::StateData) -> true

• Reason = normal | shutdown | term()
• StateName = atom()
• StateData = term()

gen_fsm - terminate/3 callback implementation. Shutdown the fsm.

Return value is ignored by the server.

unbind/1

unbind(FsmRef) -> Result

• FsmRef = Name | {Name, Node} | {global, Name} | pid()
• Result = {ok, PduResp} | {error, Error}
• PduResp = pdu()
• Error = int()

Issues an unbind operation on the session identified by FsmRef.

unbound/2

unbound(R::Event, S::StateData) -> Result

• Event = timeout | term()
• StateData = term()
• Result = {next_state, NextStateName, NextStateData} | {next_state, NextStateName, NextStateData, Timeout} | {stop, Reason, NewStateData}
• NextStateName = atom()
• NextStateData = term()
• Timeout = int() | infinity
• Reason = term()

gen_fsm - StateName/2 callback implementation. Handles async events for the state name unbound.

PDUs comming from the other peer (ESME) are received asynchronously.

unbound/3

unbound(Event, From, S::StateData) -> Result

• Event = term()
• From = {pid(), Tag}
• StateData = term()
• Result = {next_state, NextStateName, NextStateData} | {next_state, NextStateName, NextStateData, Timeout} | {reply, Reply, NextStateName, NextStateData} | {reply, Reply, NextStateName, NextStateData, Timeout} | {stop, Reason, NewStateData} | {stop, Reason, Reply, NewStateData}
• Reply = term()
• NextStateName = atom()
• NextStateData = term()
• Timeout = int() | infinity
• Reason = term()

gen_fsm - StateName/3 callback implementation. Handles events for the state name unbound.