ruby-smpp 0.1.0

data/History.txt

@@ -0,0 +1,4 @@
+== 0.1.0 2008-04-07
+
+* 1 major enhancement:
+  * Initial release

data/License.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Apparat AS
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Manifest.txt

@@ -0,0 +1,35 @@
+History.txt
+License.txt
+Manifest.txt
+README.txt
+Rakefile
+examples/sample_gateway.rb
+config/hoe.rb
+config/requirements.rb
+lib/smpp.rb
+lib/smpp/version.rb
+lib/smpp/base.rb
+lib/smpp/pdu/base.rb
+lib/smpp/pdu/bind_transceiver.rb
+lib/smpp/pdu/bind_transceiver_response.rb
+lib/smpp/pdu/deliver_sm.rb
+lib/smpp/pdu/deliver_sm_response.rb
+lib/smpp/pdu/enquire_link.rb
+lib/smpp/pdu/enquire_link_response.rb
+lib/smpp/pdu/generic_nack.rb
+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/transceiver.rb
+lib/sms.rb
+log/
+script/console
+script/destroy
+script/generate
+script/txt2html
+setup.rb
+tasks/deployment.rake
+tasks/environment.rake
+test/smpp_test.rb
+test/test_helper.rb

data/README.txt

@@ -0,0 +1,86 @@
+= Ruby-SMPP
+
+* http://ruby-smpp.rubyforge.org
+
+== DESCRIPTION:
+
+Ruby-SMPP is a Ruby implementation of the SMPP v3.4 protocol. It is suitable for writing gateway daemons that communicate with SMSCs for sending and receiving SMS messages.
+
+The implementation is based on the Ruby/EventMachine library.
+
+Glossary
+-----------------
+SMSC: SMS Center. Mobile operators normally operate an SMSC in their network. The SMSC stores and forwards SMS messages.
+MO:   Mobile Originated SMS: originated in a mobile phone, ie. sent by an end user.
+MT:   Mobile Terminated SMS: terminated in a mobile phone, ie. received by an end user.
+DR:   Delivery Report, or delivery notification. When you send an MT message, you should receive a DR after a while.
+PDU:  Protcol Base Unit, the data units that SMPP is comprised of. This implementation does _not_ implement all SMPP PDUs.
+
+Protocol
+-----------------
+The SMPP 3.4 protocol spec can be downloaded here: http://smsforum.net/SMPP_v3_4_Issue1_2.zip
+
+Testing
+-----------------
+Logica provides an SMPP simulator that you can download from http://opensmpp.logica.com/. You can 
+also sign up for a demo SMPP account at one of the many bulk-SMS providers out there.
+
+== FEATURES/PROBLEMS:
+
+* Implements only typical client subset of SMPP 3.4 with single-connection Transceiver as opposed to dual-connection Transmitter + Receiver. 
+* 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. 
+
+<pre>
+  # connect to SMSC
+  tx = EventMachine::run do             
+    $tx = EventMachine::connect(
+    host, 
+    port, 
+    Smpp::Transceiver, 
+    config,             # a property hash 
+    mo_proc,            # the proc invoked on incoming (MO) messages
+    dr_proc,            # the proc invoked on delivery reports
+    pdr_storage)        # hash-like storage for pending delivery reports
+  end
+  
+  # send a message
+  tx.send_mt(id, from, to, body)
+</pre>
+
+For a more complete example, see examples/sample_gateway.rb
+
+== REQUIREMENTS:
+
+* Eventmachine 0.10.0
+
+== INSTALL:
+
+* sudo gem install ruby-smpp
+
+== LICENSE:
+
+Copyright (c) 2008 Apparat AS
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,9 @@
+task :test do
+  ruby "test/smpp_test.rb"
+end
+
+require 'config/requirements'
+require 'config/hoe' # setup Hoe + all gem configuration
+
+Dir['tasks/**/*.rake'].each { |rake| load rake }
+

data/config/hoe.rb

@@ -0,0 +1,70 @@
+require 'smpp/version'
+
+AUTHOR = 'August Z. Flatby'
+EMAIL = "august@apparat.no"
+DESCRIPTION="Ruby-implementation of the SMPP protocol, based on EventMachine. SMPP is a protocol that allows ordinary people outside the mobile network to exchange SMS messages directly with mobile operators."
+GEM_NAME = 'ruby-smpp' 
+RUBYFORGE_PROJECT = 'ruby-smpp' # The unix name for your project
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+DOWNLOAD_PATH = "http://rubyforge.org/projects/#{RUBYFORGE_PROJECT}"
+
+@config_file = "~/.rubyforge/user-config.yml"
+@config = nil
+RUBYFORGE_USERNAME = "augustzf"
+def rubyforge_username
+  unless @config
+    begin
+      @config = YAML.load(File.read(File.expand_path(@config_file)))
+    rescue
+      puts <<-EOS
+ERROR: No rubyforge config file found: #{@config_file}
+Run 'rubyforge setup' to prepare your env for access to Rubyforge
+ - See http://newgem.rubyforge.org/rubyforge.html for more details
+      EOS
+      exit
+    end
+  end
+  RUBYFORGE_USERNAME.replace @config["username"]
+end
+
+
+REV = nil 
+# UNCOMMENT IF REQUIRED: 
+# REV = `svn info`.each {|line| if line =~ /^Revision:/ then k,v = line.split(': '); break v.chomp; else next; end} rescue nil
+VERS = Smpp::VERSION::STRING + (REV ? ".#{REV}" : "")
+RDOC_OPTS = ['--quiet', '--title', 'ruby-smpp documentation',
+    "--opname", "index.html",
+    "--line-numbers", 
+    "--main", "README",
+    "--inline-source"]
+
+class Hoe
+  def extra_deps 
+    @extra_deps.reject! { |x| Array(x).first == 'hoe' } 
+    @extra_deps
+  end 
+end
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.new(GEM_NAME, VERS) do |p|
+  p.developer(AUTHOR, EMAIL)
+  p.description = DESCRIPTION
+  p.summary = DESCRIPTION
+  p.url = HOMEPATH
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.test_globs = ["test/**/test_*.rb"]
+  p.clean_globs |= ['**/.*.sw?', '*.gem', '.config', '**/.DS_Store']  #An array of file patterns to delete on clean.
+  
+  # == Optional
+  p.changes = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  p.extra_deps = [['eventmachine', '>= 0.10.0']]
+  
+  #p.spec_extras = {}    # A hash of extra values to set in the gemspec.
+  
+end
+
+CHANGES = $hoe.paragraphs_of('History.txt', 0..1).join("\\n\\n")
+PATH    = (RUBYFORGE_PROJECT == GEM_NAME) ? RUBYFORGE_PROJECT : "#{RUBYFORGE_PROJECT}/#{GEM_NAME}"
+$hoe.remote_rdoc_dir = File.join(PATH.gsub(/^#{RUBYFORGE_PROJECT}\/?/,''), 'rdoc')
+$hoe.rsync_args = '-av --delete --ignore-errors'

data/config/requirements.rb

@@ -0,0 +1,15 @@
+require 'fileutils'
+include FileUtils
+
+require 'rubygems'
+%w[rake hoe newgem rubigen].each do |req_gem|
+  begin
+    require req_gem
+  rescue LoadError
+    puts "This Rakefile requires the '#{req_gem}' RubyGem."
+    puts "Installation: gem install #{req_gem} -y"
+    exit
+  end
+end
+
+$:.unshift(File.join(File.dirname(__FILE__), %w[.. lib]))

data/examples/sample_gateway.rb

@@ -0,0 +1,120 @@
+#!/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.
+
+gem 'ruby-smpp'
+require 'smpp'
+
+# set up logger
+Smpp::Base.logger = Logger.new(File.join(File.dirname(__FILE__), '..', 'log/sms_gateway.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 MT: #{data}"
+    from = '2210'
+    to = '4790000000'       
+    $tx.send_mt(123, from, to, data)
+    prompt
+  end
+end
+
+def prompt
+  print "Enter MT body: "
+  $stdout.flush
+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
+
+  # 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}"
+    end
+  end
+
+  # 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
+  end
+end
+
+# Start the Gateway
+begin   
+  puts "Starting SMS Gateway"  
+
+  # SMPP properties. These parameters work well with the Logica SMPP simulator.
+  # Consult the SMPP spec or your mobile operator for the correct settings of 
+  # the other properties.
+  config = {
+    :host => 'localhost',
+    :port => 6000,
+    :system_id => 'jorge',
+    :password => 'jorge',
+    :source_ton  => 0,
+    :source_npi => 1,
+    :destination_ton => 1,
+    :destination_npi => 1,
+    :source_address_range => '',
+    :destination_address_range => '',
+    :enquire_link_delay_secs => 10
+  }
+  prompt
+  start(config)  
+rescue Exception => ex
+  puts "Exception in SMS Gateway: #{ex} at #{ex.backtrace[0]}"
+end

data/lib/smpp.rb

@@ -0,0 +1,21 @@
+# SMPP v3.4 subset implementation.
+# SMPP is a short message peer-to-peer protocol typically used to communicate 
+# with SMS Centers (SMSCs) over TCP/IP.
+#
+# August Z. Flatby
+# august@apparat.no
+
+require 'logger'
+
+$:.unshift(File.dirname(__FILE__))
+require 'smpp/base.rb'
+require 'smpp/transceiver.rb'
+require 'smpp/pdu/base.rb'
+
+# Load all PDUs
+Dir.glob(File.join(File.dirname(__FILE__), 'smpp', 'pdu', '*.rb')) do |f|
+  require f unless f.match('base.rb$')
+end
+
+# Default logger. Invoke this call in your client to use another logger.
+Smpp::Base.logger = Logger.new(STDOUT)

data/lib/smpp/base.rb

@@ -0,0 +1,124 @@
+require 'timeout'
+require 'iconv'
+require 'scanf'
+require 'monitor'
+require 'eventmachine'
+
+module Smpp
+  class InvalidStateException < Exception; end
+    
+  class Base < EventMachine::Connection
+    include Smpp
+    
+    # :bound or :unbound
+    attr_accessor :state
+    
+    def Base.logger
+      @@logger
+    end
+
+    def Base.logger=(logger)
+      @@logger = logger
+    end
+
+    def logger
+      @@logger
+    end
+    
+    def initialize(config)
+      @config = config
+    end
+    
+    # invoked by EventMachine when connected
+    def post_init
+      # send Bind PDU
+      send_bind
+
+      # start timer that will periodically send enquire link PDUs
+      start_enquire_link_timer(@config[:enquire_link_delay_secs]) if @config[:enquire_link_delay_secs]
+    rescue Exception => ex
+      logger.error "Error starting RX: #{ex.message} at #{ex.backtrace[0]}"
+    end
+
+    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
+        else
+          write_pdu Pdu::EnquireLink.new
+        end
+      end
+    end
+
+    # EventMachine::Connection#receive_data
+    def receive_data(data)
+      # parse incoming PDU
+      pdu = read_pdu(data)
+      
+      # let subclass process it
+      process_pdu(pdu) if pdu
+    end
+    
+    # EventMachine::Connection#unbind
+    def unbind
+      logger.warn "EventMachine: unbind invoked in bound state" if @state == :bound
+    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
+
+    # process common PDUs
+    # returns true if no further processing necessary
+    def process_pdu(pdu)      
+      case pdu
+      when Pdu::EnquireLinkResponse
+        # nop
+      when Pdu::EnquireLink
+        write_pdu(Pdu::EnquireLinkResponse.new(pdu.sequence_number))
+      when Pdu::Unbind
+        @state = :unbound
+        write_pdu(Pdu::UnbindResponse.new(pdu.sequence_number, Pdu::Base::ESME_ROK))
+        EventMachine::stop_event_loop
+      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
+      else
+        logger.warn "(#{self.class.name}) Received unexpected PDU: #{pdu.to_human}."
+        EventMachine::stop_event_loop                
+      end
+    end
+    
+    private  
+    def write_pdu(pdu)
+      logger.debug "<- #{pdu.to_human}"
+      send_data pdu.data
+    end
+
+    def read_pdu(data)
+      pdu = nil
+      # we may either receive a new request or a response to a previous response.
+      begin        
+        pdu = Pdu::Base.create(data)
+        if !pdu
+          logger.warn "Not able to parse PDU!"
+        else
+          logger.debug "-> " + pdu.to_human          
+        end
+      rescue Exception => ex
+        logger.error "Exception while reading PDUs: #{ex} in #{ex.backtrace[0]}"
+        raise
+      end
+      pdu
+    end    
+  end
+end