Module gen_esme_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 ESME 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 ESME.

State transitions table

Possible states for the ESME 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 (SMSC) are treated asynchronously by the ESME 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_outbind/3

• ESME = pid()
• Session = pid()
• Pdu = pdu()

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

Response is ignored by the session.

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

handle_alert_notification/3

• ESME = pid()
• Session = pid()
• Pdu = pdu()

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

Response is ignored by the session.

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

handle_operation/3

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

Forwards data_sm and deliver_sm operations (from the peer SMSC) 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.

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

handle_unbind/3

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

This callback forwards unbind requests (issued by a peer SMSC) to the callback ESME.

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).

ESME is the ESME's process id, Session is the process id.

Function Index

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(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 bind_receiver operation on the session identified by FsmRef.

bind_transceiver/2

bind_transceiver(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 bind_transceiver operation on the session identified by FsmRef.

bind_transmitter/2

bind_transmitter(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 bind_transmitter operation on the session identified by FsmRef.

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.

broadcast_sm/2

broadcast_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 broadcast_sm operation on the session identified by FsmRef.

cancel_broadcast_sm/2

cancel_broadcast_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 cancel_broadcast_sm operation on the session identified by FsmRef.

cancel_sm/2

cancel_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 cancel_sm operation on the session identified by FsmRef.

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.

handle_event/3

handle_event(E::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.

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.

query_broadcast_sm/2

query_broadcast_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 query_broadcast_sm operation on the session identified by FsmRef.

query_sm/2

query_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 query_sm operation on the session identified by FsmRef.

replace_sm/2

replace_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 replace_sm operation on the session identified by FsmRef.

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_esme_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_esme_session is registered locally as TheName. If Name = {global, TheName}, the gen_esme_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 ESME (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_esme_session is not registered.

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

start_link/4

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

• Name = {local, Atom} | {global, Atom}
• Atom = atom()
• 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 ESME (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_esme_session is registered locally as Atom. If Name = {global, TheName}, the gen_esme_session is registered globally as Atom.

See also: start_link/2, 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.

submit_multi/2

submit_multi(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 submit_multi operation on the session identified by FsmRef.

submit_sm/2

submit_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 submit_sm operation on the session identified by FsmRef.

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.