ruby-smpp 0.1.1 → 0.1.2

data/CONTRIBUTORS.txt

@@ -0,0 +1,9 @@
+Maintainer:
+  August Z. Flatby <august@apparat.no>
+
+Contributors:
+  Abhishek Parolkar <abhishek@parolkar.com>
+  Taryn East <taryn@taryneast.org>
+  Josh Bryan <jbryan@cashnetusa.com>
+  Jon Wood <jonathan.wood@uk.clara.net>
+  Jacob Eiler <jacob.eiler@apide.com>

data/History.txt

@@ -1,3 +1,8 @@
+== 0.1.2 2008-12-11
+
+* Contributions:
+  * See NEWS.txt
+
 == 0.1.1 2008-10-20
 
 * Contributions:

data/Manifest.txt

@@ -1,15 +1,21 @@
+CONTRIBUTORS.txt
 History.txt
 License.txt
 Manifest.txt
+NEWS.txt
 README.txt
 Rakefile
-examples/sample_gateway.rb
 config/hoe.rb
 config/requirements.rb
+examples/PDU1.example
+examples/PDU2.example
+examples/sample_gateway.rb
+examples/sample_smsc.rb
 lib/smpp.rb
-lib/smpp/version.rb
 lib/smpp/base.rb
 lib/smpp/pdu/base.rb
+lib/smpp/pdu/bind_base.rb
+lib/smpp/pdu/bind_resp_base.rb
 lib/smpp/pdu/bind_transceiver.rb
 lib/smpp/pdu/bind_transceiver_response.rb
 lib/smpp/pdu/deliver_sm.rb
@@ -23,8 +29,11 @@ lib/smpp/pdu/submit_sm.rb
 lib/smpp/pdu/submit_sm_response.rb
 lib/smpp/pdu/unbind.rb
 lib/smpp/pdu/unbind_response.rb
+lib/smpp/server.rb
 lib/smpp/transceiver.rb
+lib/smpp/version.rb
 lib/sms.rb
+ruby-smpp.gemspec
 script/console
 script/destroy
 script/generate

data/NEWS.txt

@@ -0,0 +1,44 @@
+= 2009.01.22
+
+== Delegate methods
+
+- Some API breakage has been introduced in order to allow a delegate callback model from the transceiver. Also, the Receiver and Transmitter classes have been removed due to bad code reuse.
+
+= 2008.12.11
+
+== Updates from Jon Wood:
+
+- Closes connections cleanly instead of stopping the event loop.
+- Adds a send_concat_mt method to Transceivers (not implemented for Transmitter/Receiver), which does the neccesary encoding and message splitting to send messages > 160 characters by splitting them into multiple parts.
+
+= 2008.10.20
+ 
+== Patch from Josh Bryan:
+
+Fixes smpp/base.rb so that it can handle partial pdu's and multiple pdu's available on the stream. Previously, base.rb assumed that all data available on the TCP stream constituted the next pdu. Though this often works in low load environments, moderately high traffic environments often see multiple pdu's back to back on the stream before event machine cycles through another turn of the reactor. Also, pdu's can be split over multiple TCP packets. Thus, incomplete or multiple pdu's may be delivered to Base#receive_data, and Base needs to be able buffer and split the pdu's.
+
+= 2008.10.13
+ 
+== Patch from Taryn East:
+ 
+I added the receiver and transmitter equivalents of the transmitter class, and also hacked in some code that would support basic setup of an smpp server. Note: we were only using this to set up a test-harness for our own ruby-smpp code, so it's pretty basic and doesn't support all messages - or even do anything useful with an incoming deliver_sm. But it's better than nothing at all ;)
+
+NOTE: Taryn's patch currently lives in a separate branch (taryn-patch), awaiting merge.
+
+= 2008.06.25
+
+== Check-ins from Abhishek Parolkar
+
+I have implemented 4.5.1 section of SMPPv3.4: support for sending an MT message to multiple destination addresses.
+
+- Added system_type paramenter to BindTransceiver.new
+- Small change in submit_sm to discard '@' char in message push
+- Made submit_sm more configurable with options
+- Added PDU examples for submit_sm
+- Added example to use submit_multi and submit_sm
+ 
+= 2008.04.07
+ 
+== Initial release (August Z. Flatby)
+
+My first open source project after all these years! Ah.. it feels good.

data/README.txt

@@ -37,13 +37,13 @@ You can also send MO messages from the simulator to the sample gateway by typing
 
 == FEATURES/PROBLEMS:
 
-* Implements only typical client subset of SMPP 3.4 with single-connection Transceiver as opposed to dual-connection Transmitter + Receiver (UPDATE: see NEWS re. patch from Taryn East)
+* Implements only typical client subset of SMPP 3.4 with single-connection Transceiver.
 * Contributors are encouraged to add missing PDUs.
 * Need more test cases!
 
 == BASIC USAGE:
 
-Start the transceiver. Receive callbacks whenever incoming messages or delivery reports arrive. Send messages with Transceiver#send_mt. 
+Start the transceiver. Receive delegate callbacks whenever incoming messages or delivery reports arrive. Send messages with Transceiver#send_mt. 
 
 <pre>
   # connect to SMSC

data/examples/PDU1.example

@@ -0,0 +1,26 @@
+
+This is the PDU being sent when sender address is numeric
+
+type_name: submit_sm
+command_id: 4 = 0x00000004
+command_status: 0 = 0x00000000
+sequence_number: 3 = 0x00000003
+service_type: "1"
+source_addr_ton: 2 = 0x00000002
+source_addr_npi: 1 = 0x00000001
+source_addr: "919900000000" 	#number masked
+dest_addr_ton: 2 = 0x00000002
+dest_addr_npi: 1 = 0x00000001
+destination_addr: "919900000000"  #number masked
+esm_class: 3 = 0x00000003
+protocol_id: 0 = 0x00000000
+priority_flag: 0 = 0x00000000
+schedule_delivery_time: NULL
+validity_period: NULL
+registered_delivery: 1 = 0x00000001
+replace_if_present_flag: 0 = 0x00000000
+data_coding: 0 = 0x00000000
+sm_default_msg_id: 0 = 0x00000000
+sm_length: 9 = 0x00000009
+short_message: "test smpp"
+

data/examples/PDU2.example

@@ -0,0 +1,26 @@
+
+Example PDU when sender address is an alphanumeric keyword
+
+type_name: submit_sm
+command_id: 4 = 0x00000004
+command_status: 0 = 0x00000000
+sequence_number: 5 = 0x00000005
+service_type: "1"
+source_addr_ton: 5 = 0x00000005
+source_addr_npi: 0 = 0x00000000
+source_addr: "RUBYSMPP"
+dest_addr_ton: 2 = 0x00000002
+dest_addr_npi: 1 = 0x00000001
+destination_addr: "919900000000" # number masked
+esm_class: 3 = 0x00000003
+protocol_id: 0 = 0x00000000
+priority_flag: 0 = 0x00000000
+schedule_delivery_time: NULL
+validity_period: NULL
+registered_delivery: 1 = 0x00000001
+replace_if_present_flag: 0 = 0x00000000
+data_coding: 0 = 0x00000000
+sm_default_msg_id: 0 = 0x00000000
+sm_length: 5 = 0x00000005
+short_message: "hello"
+

data/examples/sample_gateway.rb

@@ -1,24 +1,6 @@
-#!/usr/bin/env ruby
-
-# Sample SMPP SMS Gateway. A proper SMS gateway listens for MOs (incoming
-# messages) and DRs (delivery reports), and submit MTs (outgoing messages).
-#
-# An SMS gateway can be the endpoint for a shortcode. For example, the 
-# shortcode 2210 in Norway is implemented as a number of gateways like this
-# (one for each mobile operator). Hence, it will receive MOs (deliver_sm) from
-# end users addressed to shortcode 2210 and send MTs (submit_sm) to end users
-# from shortcode 2210.
-#
-# This gateway logs activity (including incoming MO and DR) to log/sms_gateway.log 
-# and accepts outgoing (MT) messages from the console. This may be useful for
-# testing your SMPP setup.
-
-require 'rubygems'
-gem 'ruby-smpp'
-require 'smpp'
-
-# set up logger
-Smpp::Base.logger = Logger.new('sms_gateway.log')
+#!/usr/bin/env ruby0
+LOGFILE = File.dirname(__FILE__) + "/sms_gateway.log"
+Smpp::Base.logger = Logger.new(LOGFILE)
 
 # the transceiver
 $tx = nil
@@ -31,95 +13,127 @@ module KeyboardHandler
   def receive_line(data)
     puts "Sending MT: #{data}"
     from = '2210'
-    to = '4790000000'       
-    $tx.send_mt(123, from, to, data)
-
-
-# if you want to send messages with custom options, uncomment below code, this configuration allows the sender ID to be alpha numeric
-#    $tx.send_mt(123, "RubySmpp", to, "Testing RubySmpp as sender id",{
-#    :source_addr_ton=> 5,
-#	:service_type => 1,
-#	:source_addr_ton => 5,
-#	:source_addr_npi => 0 ,
-#	:dest_addr_ton => 2, 
-#	:dest_addr_npi => 1, 
-#	:esm_class => 3 ,
-#	:protocol_id => 0, 
-#	:priority_flag => 0,
-#	:schedule_delivery_time => nil,
-#	:validity_period => nil,
-#	:registered_delivery=> 1,
-#	:replace_if_present_flag => 0,
-#	:data_coding => 0,
-#	:sm_default_msg_id => 0 
-#     })   
-
-# if you want to send message to multiple destinations , uncomment below code
-#    $tx.send_multi_mt(123, from, ["919900000001","919900000002","919900000003"], "I am echoing that ruby-smpp is great")  
+    to = '4790000000'     
+    msg_id = 123  
+    $tx.send_mt(msg_id, from, to, data)
+
+
+    # if you want to send messages with custom options, uncomment below code, this configuration allows the sender ID to be alpha numeric
+    #    $tx.send_mt(123, "RubySmpp", to, "Testing RubySmpp as sender id",{
+    #    :source_addr_ton=> 5,
+    #	:service_type => 1,
+    #	:source_addr_ton => 5,
+    #	:source_addr_npi => 0 ,
+    #	:dest_addr_ton => 2, 
+    #	:dest_addr_npi => 1, 
+    #	:esm_class => 3 ,
+    #	:protocol_id => 0, 
+    #	:priority_flag => 0,
+    #	:schedule_delivery_time => nil,
+    #	:validity_period => nil,
+    #	:registered_delivery=> 1,
+    #	:replace_if_present_flag => 0,
+    #	:data_coding => 0,
+    #	:sm_default_msg_id => 0 
+    #     })   
+
+    # if you want to send message to multiple destinations , uncomment below code
+    #    $tx.send_multi_mt(123, from, ["919900000001","919900000002","919900000003"], "I am echoing that ruby-smpp is great")  
     prompt
   end
+  
+  def prompt
+    print "Enter MT body: "
+    $stdout.flush
+  end
 end
 
-def prompt
-  print "Enter MT body: "
-  $stdout.flush
-end
+class SampleGateway
+  include KeyboardHandler
+  
+  def logger
+    Smpp::Base.logger
+  end
 
-def logger
-  Smpp::Base.logger
-end
+  def start(config)
+    # The transceiver sends MT messages to the SMSC. It needs a storage with Hash-like
+    # semantics to map SMSC message IDs to your own message IDs.
+    pdr_storage = {} 
+
+    # The block invoked when we receive an MO message from the SMSC
+    mo_proc = Proc.new do |sender, receiver, msg|
+      begin
+        # This is where you'd enqueue or store the MO message for further processing.
+        logger.info "Received MO from <#{sender}> to <#{receiver}>: <#{msg}>"
+      rescue Exception => ex
+        logger.error "Exception processing MO: #{ex}"
+      end
+    end
 
-def start(config)
-  # The transceiver sends MT messages to the SMSC. It needs a storage with Hash-like
-  # semantics to map SMSC message IDs to your own message IDs.
-  pdr_storage = {} 
-
-  # The block invoked when we receive an MO message from the SMSC
-  mo_proc = Proc.new do |sender, receiver, msg|
-    begin
-      # This is where you'd enqueue or store the MO message for further processing.
-      logger.info "Received MO from <#{sender}> to <#{receiver}>: <#{msg}>"
-    rescue Exception => ex
-      logger.error "Exception processing MO: #{ex}"
+    # Invoked on delivery reports
+    dr_proc = Proc.new do |msg_reference, stat, dr_pdu|
+      begin
+        # The SMSC returns its own message reference. Look up (and delete) our stored objects
+        # based on this reference.
+        # 
+        # The short_message attribute contains details on the current delivery status of the
+        # message.
+        pending_message = pdr_storage.delete(msg_reference)
+        logger.info "Received DR for #{pending_message}. Stat: #{stat} SM: #{dr_pdu.short_message}"
+      rescue Exception => ex
+        logger.error "Error processing DR: #{ex}"
+      end
     end
-  end
 
-  # Invoked on delivery reports
-  dr_proc = Proc.new do |msg_reference, operator_status_code|
-    begin
-      # The SMSC returns its own message reference. Look up (and delete) our stored objects
-      # based on this reference.
-      pending_message = pdr_storage.delete(msg_reference)
-      logger.info "Received DR for #{pending_message}: #{operator_status_code}"
-    rescue Exception => ex
-      logger.error "Error processing DR: #{ex}"
+    # Run EventMachine in loop so we can reconnect when the SMSC drops our connection.
+    prompt
+    loop do
+      EventMachine::run do             
+        $tx = EventMachine::connect(
+        config[:host], 
+        config[:port], 
+        Smpp::Transceiver, 
+        config, 
+        self  # self is delegate
+        )     
+
+        # Start consuming MT messages (in this case, from the console)
+        # Normally, you'd hook this up to a message queue such as Starling
+        # or ActiveMQ via STOMP.
+        EventMachine::open_keyboard(KeyboardHandler)
+      end
+      logger.warn "Event loop stopped. Restarting in 5 seconds.."
+      sleep 5
     end
+
   end
+  # Delegate methods that will receive callbacks on various events
 
-  # Run EventMachine in loop so we can reconnect when the SMSC drops our connection.
-  loop do
-    EventMachine::run do             
-      $tx = EventMachine::connect(
-          config[:host], 
-          config[:port], 
-          Smpp::Transceiver, 
-          config, 
-          mo_proc, 
-          dr_proc, 
-          pdr_storage)       
-      # Start consuming MT messages (in this case, from the console)
-      # Normally, you'd hook this up to a message queue such as Starling
-      # or ActiveMQ via STOMP.
-      EventMachine::open_keyboard(KeyboardHandler)
-    end
-    logger.warn "Event loop stopped. Restarting in 5 seconds.."
-    sleep 5
+  def mo_received(transceiver, source_addr, destination_addr, short_message)
+    logger.info "Delegate: mo_received: from #{source_addr} to #{destination_addr}: #{short_message}"
+  end
+
+  def delivery_report_received(transceiver, msg_reference, stat, pdu)
+    logger.info "Delegate: delivery_report_received: ref #{msg_reference} stat #{stat} pdu #{pdu}"
+  end
+
+  def message_accepted(transceiver, mt_message_id, smsc_message_id)
+    logger.info "Delegate: message_sent: id #{mt_message_id} smsc ref id: #{smsc_message_id}"
+  end
+
+  def bound(transceiver)
+    logger.info "Delegate: transceiver bound"
+  end
+
+  def unbound(transceiver)  
+    logger.info "Delegate: transceiver unbound"
+    EventMachine::stop_event_loop
   end
 end
 
 # Start the Gateway
 begin   
-  puts "Starting SMS Gateway"  
+  puts "Starting SMS Gateway. Check the log at #{LOGFILE}"  
 
   # SMPP properties. These parameters work well with the Logica SMPP simulator.
   # Consult the SMPP spec or your mobile operator for the correct settings of 
@@ -129,7 +143,7 @@ begin
     :port => 6000,
     :system_id => 'hugo',
     :password => 'ggoohu',
-	  :system_type => 'vma', # default given according to SMPP 3.4 Spec
+    :system_type => 'vma', # default given according to SMPP 3.4 Spec
     :interface_version => 52,
     :source_ton  => 0,
     :source_npi => 1,
@@ -138,9 +152,9 @@ begin
     :source_address_range => '',
     :destination_address_range => '',
     :enquire_link_delay_secs => 10
-  }
-  prompt
-  start(config)  
+  }  
+  gw = SampleGateway.new
+  gw.start(config)  
 rescue Exception => ex
-  puts "Exception in SMS Gateway: #{ex} at #{ex.backtrace[0]}"
+  puts "Exception in SMS Gateway: #{ex} at #{ex.backtrace.join("\n")}"
 end

data/examples/sample_smsc.rb

@@ -0,0 +1,103 @@
+#!/usr/bin/env ruby
+
+# Sample SMPP SMS Gateway. 
+
+require 'rubygems'
+gem 'ruby-smpp'
+require 'smpp'
+require 'smpp/server'
+
+# set up logger
+Smpp::Base.logger = Logger.new('smsc.log')
+
+# the transceiver
+$tx = nil
+
+# We use EventMachine to receive keyboard input (which we send as MT messages).
+# A "real" gateway would probably get its MTs from a message queue instead.
+module KeyboardHandler
+  include EventMachine::Protocols::LineText2
+
+  def receive_line(data)
+    puts "Sending MO: #{data}"
+    from = '1111111111'
+    to = '1111111112'       
+    $tx.send_mo(from, to, data)
+
+
+# if you want to send messages with custom options, uncomment below code, this configuration allows the sender ID to be alpha numeric
+#    $tx.send_mt(123, "RubySmpp", to, "Testing RubySmpp as sender id",{
+#    :source_addr_ton=> 5,
+#	:service_type => 1,
+#	:source_addr_ton => 5,
+#	:source_addr_npi => 0 ,
+#	:dest_addr_ton => 2, 
+#	:dest_addr_npi => 1, 
+#	:esm_class => 3 ,
+#	:protocol_id => 0, 
+#	:priority_flag => 0,
+#	:schedule_delivery_time => nil,
+#	:validity_period => nil,
+#	:registered_delivery=> 1,
+#	:replace_if_present_flag => 0,
+#	:data_coding => 0,
+#	:sm_default_msg_id => 0 
+#     })   
+
+# if you want to send message to multiple destinations , uncomment below code
+#    $tx.send_multi_mt(123, from, ["919900000001","919900000002","919900000003"], "I am echoing that ruby-smpp is great")  
+    prompt
+  end
+end
+
+def prompt
+  print "Enter MO body: "
+  $stdout.flush
+end
+
+def logger
+  Smpp::Base.logger
+end
+
+def start(config)
+
+  # Run EventMachine in loop so we can reconnect when the SMSC drops our connection.
+  loop do
+    EventMachine::run do             
+      $tx = EventMachine::start_server(
+          config[:host], 
+          config[:port], 
+          Smpp::Server,
+          config
+          )       
+    end
+    logger.warn "Event loop stopped. Restarting in 5 seconds.."
+    sleep 5
+  end
+end
+
+# Start the Gateway
+begin   
+  puts "Starting SMS Gateway"  
+
+  # SMPP properties. These parameters the ones provided sample_gateway.rb and
+  # will work with it.
+  config = {
+    :host => 'localhost',
+    :port => 6000,
+    :system_id => 'hugo',
+    :password => 'ggoohu',
+	  :system_type => 'vma', # default given according to SMPP 3.4 Spec
+    :interface_version => 52,
+    :source_ton  => 0,
+    :source_npi => 1,
+    :destination_ton => 1,
+    :destination_npi => 1,
+    :source_address_range => '',
+    :destination_address_range => '',
+    :enquire_link_delay_secs => 10
+  }
+  start(config)  
+rescue Exception => ex
+  puts "Exception in SMS Gateway: #{ex} at #{ex.backtrace[0]}"
+end

data/lib/smpp/base.rb

@@ -1,6 +1,3 @@
-require 'rubygems'
-gem 'eventmachine'
-
 require 'timeout'
 require 'iconv'
 require 'scanf'
@@ -16,6 +13,15 @@ module Smpp
     # :bound or :unbound
     attr_accessor :state
     
+    # queries the state of the transmitter - is it bound?
+    def unbound?
+      @state == :unbound
+    end
+    
+    def bound?
+      @state == :bound
+    end
+    
     def Base.logger
       @@logger
     end
@@ -29,14 +35,16 @@ module Smpp
     end
     
     def initialize(config)
+      @state = :unbound
       @config = config
       @data = ""
     end
     
     # invoked by EventMachine when connected
     def post_init
-      # send Bind PDU
-      send_bind
+      # send Bind PDU if we are a binder (eg
+      # Receiver/Transmitter/Transceiver
+      send_bind unless defined?(am_server?) && am_server?
 
       # start timer that will periodically send enquire link PDUs
       start_enquire_link_timer(@config[:enquire_link_delay_secs]) if @config[:enquire_link_delay_secs]
@@ -44,14 +52,27 @@ module Smpp
       logger.error "Error starting RX: #{ex.message} at #{ex.backtrace[0]}"
     end
 
+    # sets up a periodic timer that will periodically enquire as to the
+    # state of the connection
+    # Note: to add in custom executable code (that only runs on an open
+    # connection), derive from the appropriate Smpp class and overload the
+    # method named: periodic_call_method
     def start_enquire_link_timer(delay_secs)
       logger.info "Starting enquire link timer (with #{delay_secs}s interval)"
       EventMachine::PeriodicTimer.new(delay_secs) do 
         if error?
-          logger.warn "Link timer: Connection is in error state. Terminating loop."
-          EventMachine::stop_event_loop
+          logger.warn "Link timer: Connection is in error state. Disconnecting."
+          close_connection
+        elsif unbound?
+          logger.warn "Link is unbound, waiting until next #{delay_secs} interval before querying again"
         else
-          write_pdu Pdu::EnquireLink.new
+
+          # if the user has defined a method to be called periodically, do
+          # it now - and continue if it indicates to do so
+          rval = defined?(periodic_call_method) ? periodic_call_method : true
+
+          # only send an OK if this worked
+          write_pdu Pdu::EnquireLink.new if rval 
         end
       end
     end
@@ -80,14 +101,16 @@ module Smpp
     end
     
     # EventMachine::Connection#unbind
+    # Invoked by EM when connection is closed. Delegates should consider
+    # breaking the event loop and reconnect when they receive this callback.
     def unbind
-      logger.warn "EventMachine: unbind invoked in bound state" if @state == :bound
+      if @delegate.respond_to?(:unbound)
+        @delegate.unbound(self)
+      end
     end
     
     def send_unbind
-      #raise rescue logger.debug "Unbinding, now?? #{$!.backtrace[1..5].join("\n")}"
       write_pdu Pdu::Unbind.new
-      # leave it to the subclass to process the UnbindResponse
       @state = :unbound
     end
 
@@ -102,20 +125,20 @@ module Smpp
       when Pdu::Unbind
         @state = :unbound
         write_pdu(Pdu::UnbindResponse.new(pdu.sequence_number, Pdu::Base::ESME_ROK))
-        EventMachine::stop_event_loop
+        close_connection
       when Pdu::UnbindResponse      
         logger.info "Unbound OK. Closing connection."
         close_connection
       when Pdu::GenericNack
         logger.warn "Received NACK! (error code #{pdu.error_code})."
-        # we don't take this lightly: stop the event loop
-        EventMachine::stop_event_loop
+        # we don't take this lightly: close the connection
+        close_connection
       else
         logger.warn "(#{self.class.name}) Received unexpected PDU: #{pdu.to_human}."
-        EventMachine::stop_event_loop                
+        close_connection
       end
     end
-    
+
     private  
     def write_pdu(pdu)
       logger.debug "<- #{pdu.to_human}"