anjlab-ruby-smpp 0.6.0

data/CHANGELOG

@@ -0,0 +1,52 @@
+= 0.3.0
+* Added begin/rescue handling in receive_data to keep the connection alive. Delegates can implement data_error(Exception) and re-raise the error if they wish to break the connection.
+
+= 0.1.3
+* Transition maintenance from August to Ray Krueger
+* Changed the expected signature of transceiver delegates to use the full PDU instead of picking off attributes one by one
+* Added support for parsing optional parameters from delivery receipts in deliver_sm PDUs (this is also the fix for trailing bytes from MOs)
+
+= 0.1.2 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/CONTRIBUTORS.txt

@@ -0,0 +1,11 @@
+Maintainer:
+  Ray Krueger <raykrueger@gmail.com>
+  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>
+  Valdis Pornieks <valdis@ithouse.lv>

data/Gemfile

@@ -0,0 +1,8 @@
+source 'http://rubygems.org'
+
+gem "eventmachine", ">= 0.10.0"
+
+group :development do
+  gem "jeweler"
+  gem "rake"
+end

data/Gemfile.lock

@@ -0,0 +1,18 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    eventmachine (0.12.10)
+    git (1.2.5)
+    jeweler (1.6.4)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+    rake (0.9.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  eventmachine (>= 0.10.0)
+  jeweler
+  rake

data/LICENSE

@@ -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/README.rdoc

@@ -0,0 +1,89 @@
+= Ruby-SMPP
+
+== 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.
+
+<b>NOTE: Breaking change from 0.1.2 to 0.1.3</b>. See below.
+
+For help please use the Google group here: http://groups.google.com/group/ruby-smpp/topics
+=== 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/Sample Code
+
+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.
+
+For a quick test, download smscsim.jar and smpp.jar from the Logica site, and start the simulator by typing:
+
+  java -cp smscsim.jar:smpp.jar com.logica.smscsim.Simulator
+
+Then type 1 (start simulation), and enter 6000 for port number. The simulator then starts a server socket on a background thread. In another terminal window, start the sample sms gateway from the ruby-smpp/examples directory by typing:
+
+  ruby sample_gateway.rb
+
+You will be able to send MT messages from the sample gateway terminal window by typing the message body. In the simulator terminal window you should see SMPP PDUs being sent from the sample gateway. 
+
+You can also send MO messages from the simulator to the sample gateway by typing 7 (log to screen off) and then 4 (send message). MO messages received by the sample gateway will be logged to ./sms_gateway.log.
+
+== FEATURES/PROBLEMS:
+
+
+* Implements only typical client subset of SMPP 3.4 with single-connection Transceiver.
+* Contributors are encouraged to add missing PDUs.
+
+== BASIC USAGE:
+
+Start the transceiver. Receive delegate callbacks whenever incoming messages or delivery reports arrive. Send messages with Transceiver#send_mt. 
+
+  # connect to SMSC
+  tx = EventMachine::run do             
+    $tx = EventMachine::connect(
+    host, 
+    port, 
+    Smpp::Transceiver, 
+    config,             # a property hash 
+    delegate            # delegate class that will receive callbacks on MOs and DRs and other events
+  end
+  
+  # send a message
+  tx.send_mt(id, from, to, body)
+
+As of 0.1.3 the delegate method signatures are as follows:
+*   mo_received(transceiver, deliver_sm_pdu)
+*   delivery_report_received(transceiver, deliver_sm_pdu)
+*   message_accepted(transceiver, mt_message_id, submit_sm_response_pdu)
+*   message_rejected(transceiver, mt_message_id, submit_sm_response_pdu)
+*   bound(transceiver)
+*   unbound(transceiver)
+
+Where 'pdu' above is the actual actual instance of the Smpp:Pdu:: class created.
+
+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
+Released under the MIT license.

data/Rakefile

@@ -0,0 +1,53 @@
+require File.expand_path('../config/environment', __FILE__)
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+    gem.name = "ruby-smpp"
+    gem.summary = %Q{Ruby implementation of the SMPP protocol, based on EventMachine.}
+    gem.description = gem.summary + " SMPP is a protocol that allows ordinary people outside the mobile network to exchange SMS messages directly with mobile operators."
+    gem.email = "raykrueger@gmail.com"
+    gem.homepage = "http://github.com/raykrueger/ruby-smpp"
+    gem.authors = ["Ray Krueger", "August Z. Flatby"]
+    gem.rubyforge_project = gem.name
+
+    gem.extra_rdoc_files = ["README.rdoc", "CHANGELOG", "CONTRIBUTORS.txt"]
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "ruby-smpp #{version}"
+  rdoc.rdoc_files.include('README*', "CHANGELOG", "CONTRIBUTORS.txt", "LICENSE")
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.6.0

data/config/environment.rb

@@ -0,0 +1,2 @@
+require "rubygems"
+require "bundler/setup"

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

@@ -0,0 +1,137 @@
+#!/usr/bin/env ruby
+
+# Sample SMS gateway that can receive MOs (mobile originated messages) and
+# DRs (delivery reports), and send MTs (mobile terminated messages).
+# MTs are, in the name of simplicity, entered on the command line in the format
+# <sender> <receiver> <message body>
+# MOs and DRs will be dumped to standard out.
+
+require 'rubygems'
+require File.dirname(__FILE__) + '/../lib/smpp'
+
+LOGFILE = File.dirname(__FILE__) + "/sms_gateway.log"
+Smpp::Base.logger = Logger.new(LOGFILE)
+
+# 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)
+    sender, receiver, *body_parts = data.split
+    unless sender && receiver && body_parts.size > 0
+      puts "Syntax: <sender> <receiver> <message body>"      
+    else
+      body = body_parts.join(' ')
+      puts "Sending MT from #{sender} to #{receiver}: #{body}"  
+      SampleGateway.send_mt(sender, receiver, body)
+    end
+    prompt
+  end
+  
+  def prompt
+    print "MT: "
+    $stdout.flush
+  end
+end
+
+class SampleGateway
+  
+  # MT id counter. 
+  @@mt_id = 0
+  
+  # expose SMPP transceiver's send_mt method
+  def self.send_mt(*args)
+    @@mt_id += 1
+    @@tx.send_mt(@@mt_id, *args)
+  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 = {} 
+
+    # Run EventMachine in loop so we can reconnect when the SMSC drops our connection.
+    puts "Connecting to SMSC..."
+    loop do
+      EventMachine::run do             
+        @@tx = EventMachine::connect(
+          config[:host], 
+          config[:port], 
+          Smpp::Transceiver, 
+          config, 
+          self    # delegate that will receive callbacks on MOs and DRs and other events
+        )     
+        print "MT: "
+        $stdout.flush
+        
+        # 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
+      puts "Disconnected. Reconnecting in 5 seconds.."
+      sleep 5
+    end
+  end
+  
+  # ruby-smpp delegate methods 
+
+  def mo_received(transceiver, pdu)
+    logger.info "Delegate: mo_received: from #{pdu.source_addr} to #{pdu.destination_addr}: #{pdu.short_message}"
+  end
+
+  def delivery_report_received(transceiver, pdu)
+    logger.info "Delegate: delivery_report_received: ref #{pdu.msg_reference} stat #{pdu.stat}"
+  end
+
+  def message_accepted(transceiver, mt_message_id, pdu)
+    logger.info "Delegate: message_accepted: id #{mt_message_id} smsc ref id: #{pdu.message_id}"
+  end
+
+  def message_rejected(transceiver, mt_message_id, pdu)
+    logger.info "Delegate: message_rejected: id #{mt_message_id} smsc ref id: #{pdu.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. Please 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 
+  # the other properties.
+  config = {
+    :host => '127.0.0.1',
+    :port => 6000,
+    :system_id => 'hugo',
+    :password => 'ggoohu',
+    :system_type => '', # 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
+  }  
+  gw = SampleGateway.new
+  gw.start(config)  
+rescue Exception => ex
+  puts "Exception in SMS Gateway: #{ex} at #{ex.backtrace.join("\n")}"
+end