developergarden_sdk 0.0.8

data/LICENSE

@@ -0,0 +1,3 @@
+== developergarden_sdk_handsoap
+
+Put appropriate LICENSE for your project here.

data/README

@@ -0,0 +1,177 @@
+== developergarden_sdk
+This library provides access to open development services of the Deutsche Telekom AG.
+For more details about the services see
+ http://www.developergarden.com
+
+Depending on your operating system you might want to skip the "sudo" command prior to the
+commands listed here.
+
+=== Dependencies
+In order to use this library the following dependencies need to be met: 
+  Ruby 1.8.6
+  Ruby Gems >= 1.3.1
+
+There might be issues with Ruby 1.8.7 regarding to curb so it is highly recommended to use Ruby 1.8.6.
+
+==== Gems
+The following gems need to be installed:
+* handsoap (Version 0.2.8)
+* nokogiri
+* httpclient (Version 2.1.14)
+* htmlentities
+
+=== Install the handsoap gem
+For production use the official release of handsoap should be installed.
+More information about handsoap can be found at:
+ http://github.com/troelskn/handsoap/tree/master
+ 
+==== Install official handsoap release
+ gem sources -a http://gems.github.com
+ sudo gem install troelskn-handsoap 
+
+==== Install handsoap developer version
+If you want to use the bleeding edge version of handsoap proceed as follows.
+Note that you do not need to perform these steps if you have already installed the official release!
+
+Checkout handsoap from github
+ git clone git://github.com/troelskn/handsoap.git
+
+Install jeweler
+ sudo gem install jeweler
+
+Build handsoap package
+ cd handsoap_git_repo
+ rake build
+
+Install the resulting gem file
+ cd pkg
+ sudo gem install handsoap-0.2.7.gem
+
+Attention: if you you use the development version you might need to change the gem statement in
+   basic_service.rb from
+
+   gem 'troelskn-handsoap'
+
+   to
+
+   gem 'handsoap'
+
+=== Installation of the developergarden_sdk Gem
+Install the gem using the following command
+ gem install developergarden_sdk-0.0.x.gem
+
+Where x stands for the current version. For the version 0.0.4 this could look like this:
+ gem install developergarden_sdk-0.0.x.gem
+
+=== Basic usage
+You can use the gem from pure Ruby applications and of course from Ruby on Rails apps as well.
+
+==== To use the gem from your Ruby app:
+
+ require 'rubygems'
+ gem 'developergarden_sdk'
+ require 'token_Service/token_service'
+ require 'sms_service/sms_service'
+ require 'voice_call_service/voice_call_service'
+ require 'quota_service/quota_service'
+ require 'service_environment'
+
+==== Ruby Example to send a sms
+ #!/usr/bin/env ruby -d
+
+ require 'rubygems'
+ gem 'developergarden_sdk'
+ require 'token_Service/token_service'
+ require 'sms_service/sms_service'
+ require 'service_environment'
+
+ sms = SmsService::SmsService.new("<USER>@t-online.de", "<PASSWORD>")
+ sms_response = sms.send_sms("+49177 0000001", "Your message text.", "RubySDK", ServiceEnvironment.PRODUCTION, "")
+ 
+
+==== To use your gem from your Ruby on Rails app
+In your environment.rb add the following line in the config block:
+ config.gem 'developergarden_sdk'
+
+==== Ruby on Rails Example
+
+ class SmsNotification
+
+   USERNAME = "<USER>@t-online.de"
+   PASSWORD = "<PASSWORD>"
+
+   # Send SMS to Numbers.
+   def send_sms(number, message, originator, environment = 2)
+
+   # Create new SmsService instance
+   @sms = SmsService::SmsService.new(USERNAME, PASSWORD)
+
+   # Send SMS to cell phone
+   @sms.send_sms(number, message, originator, environment)
+   
+   end
+
+ end
+
+=== More Examples
+In order to see more examples have a look the unit tests included in the gem's source code.
+You might also want to have a look at the actual source code and source code comments.
+
+=== Debug
+Per default all generated and received soap xml messages are not visible. These can be print to stdout for debugging
+purposes by starting the ruby interpreter with the -d option. You will then see all http xml soap requests and responses.
+This can be done by invoking your ruby app by using a shebang like this:
+ #!/usr/bin/ruby -d
+
+=== Testing
+Before you run the tests you will need to modify config/test_settings.yml by entering your developer garden credentials.
+
+Executing tests will be done in the "sandbox" or "mock" environment which are free of charge.
+Be ware that the services itself have quotas on these test environments so your tests may fail after a while.
+The quotas are on a daily basis so they should pass again the next day.
+
+Failures when reaching the SANDBOX QUOTA might look like this:
+ 0030 quotas have exceeded
+
+Phone numbers in test files are fictive and for testing purposes only.
+
+The testsuite can be run by invoking the test raketask.
+ cd /home/yourhome/developergarden_sdk
+ rake test
+
+In order to run a single test perform the following command:
+ cd /home/yourhome/developergarden_sdk/lib
+ ruby -d ../test/voice_call_service_test.rb --name teardown_call
+
+==== QuotaService
+* QuotaService can be tested as it is. There is no need to pass an environment such as "production" or "sandbox" because
+it is free of charge.
+
+==== SmsService
+* SmsService can be tested using the "sandbox" environment. Be aware that there is a 5 credit quota per day. So you can
+send 5 test sms per day. After that you will receive a corresponding quota error message.
+
+==== VoiceCallService
+* In the "sandbox" environment there is a quota limit of 5 calls per day (each up to 10 sec) for the VoiceCallService
+* In the "production" environment a call may not last more than 60 minutes. After 60 min the call will be cancelled.
+* There is also a quota for the "mock" environment.
+
+For more information about service environments have a look at the documentation at http://www.developergarden.com
+
+=== Build the developergarden_sdk gem
+You can build the gem by invoking the gem rake task
+ rake gem
+The resulting gem will be generated to the pkg/ directory and can be installed like this:
+ sudo gem install developergarden_sdk-0.0.6.gem
+Depending on the current version number you will need to adapt the gem filename correspondingly.
+
+==More Information
+More information about developer garden services can be found at:
+ http://www.developergarden.com
+
+==FAQ
+=== Did not understand "MustUnderstand" header(s)
+ Handsoap::Fault: Handsoap::Fault { :code => 'soapenv:MustUnderstand', :reason => 'Did not understand "MustUnderstand" header(s):{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd}Security' }
+
+You will receive this error message if a mandatory header element is not present or the remote service was unable to process it.
+Most likely this will happen if something is wrong during the authentication process such as missing parameters like username, password.

data/Rakefile

@@ -0,0 +1,63 @@
+#
+# To change this template, choose Tools | Templates
+# and open the template in the editor.
+
+
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'rake/testtask'
+require 'fileutils'
+
+spec = Gem::Specification.new do |s|
+  s.name = 'developergarden_sdk'
+  s.version = '0.0.8'
+  s.homepage = 'http://www.developergarden.com'
+  s.has_rdoc = true
+  s.extra_rdoc_files = ['README', 'LICENSE']
+  s.summary = 'Offers a ruby client for the open development services such as send SMS, voice call and quota management of the Deutsche Telekom AG. See also http://www.developergarden.com.'
+  s.description = s.summary
+  s.author = 'Julian Fischer / Aperto move GmbH'
+  s.email = 'ruby@developergarden.com'
+  # s.executables = ['your_executable_here']
+
+  # GEM dependencies
+  s.add_dependency 'httpclient', '= 2.1.4'
+  s.add_dependency 'nokogiri', '>= 1.3.1'
+  s.add_dependency 'troelskn-handsoap', '= 0.2.8'
+  s.add_dependency 'htmlentities', '>= 4.0.0'
+
+  s.files = %w(LICENSE README Rakefile) + Dir.glob("{bin,lib,spec}/**/*")
+  s.require_path = "lib"
+  s.bindir = "bin"
+end
+
+Rake::GemPackageTask.new(spec) do |p|
+  p.gem_spec = spec
+  p.need_tar = true
+  p.need_zip = true
+end
+
+Rake::RDocTask.new do |rdoc|
+  files =['README', 'LICENSE', 'lib/**/*.rb']
+  rdoc.rdoc_files.add(files)
+  rdoc.main = "README" # page to start on
+  rdoc.title = "developergarden_sdk Docs"
+  rdoc.rdoc_dir = 'doc/rdoc' # rdoc output folder
+  rdoc.options << '--line-numbers'
+  rdoc.options << '--all'
+  rdoc.options << '--charset=UTF-8'
+end
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList['test/**/*.rb']
+end
+
+desc "update_plugin"
+task :update_plugin do
+  sh %{ cp -R lib/* plugin/developergarden_sdk/lib/ }
+  sh %{ cp -R test/* plugin/developergarden_sdk/test/ }
+end
+

data/lib/authenticated_service.rb

@@ -0,0 +1,30 @@
+require File.dirname(__FILE__) + '/basic_service'
+require File.dirname(__FILE__) + '/token_service/token_service'
+
+# Base service for all services demanding a security token.
+class AuthenticatedService < BasicService
+
+  def initialize(username, password)
+    super(username, password)
+
+    @token_service = TokenService::TokenService.new(@username, @password)
+  end
+
+  # Invokes the given action and also adds the security token to the SOAP header.
+  # Using this method authentication is totally hidden from the rest of the application.
+  def invoke_authenticated(action, &block)
+
+    security_token = @token_service.get_security_token
+
+    response = invoke(action) do |message|
+      doc = message.document
+      
+      # Build the login header
+      build_service_header(doc, security_token)
+
+      yield(message, doc)
+    end
+
+    return response
+  end
+end

data/lib/basic_response.rb

@@ -0,0 +1,45 @@
+require File.dirname(__FILE__) + '/service_exception'
+
+# Base class for service responses.
+class BasicResponse
+  attr_accessor :error_code, :error_message
+
+  # Constructor
+  def inizialize
+  end
+
+  # Constructor.
+  # ===Parameters
+  # <tt>response_xml</tt>:: Xml as returned by a <tt>status</tt>-method call.
+  # <tt>raise_exception_on_error</tt>:: Xml as returned by a <tt>status</tt>-method call.  
+  def initialize(response_xml, raise_exception_on_error = true)
+    doc = response_xml.document
+
+    @error_code      = doc.xpath("//errorCode").text
+    @error_message   = doc.xpath("//errorMessage").text
+
+    raise_on_error(response_xml) if raise_exception_on_error
+  end
+
+  # Returns <tt>self.inspect</tt>. Good for debugging purposes.
+  def to_s
+    return self.inspect
+  end
+
+  # Raises an exception if the response is an error.
+  # Since in some response types the error code is not named "errorCode" it is not possible
+  # to call this method only in the constructur of this base class.
+  # This is sufficient for services using the BaseResponse directly but subclasses of BaseResponse
+  # need to call this method at the end of their constructure <tt>initialize</tt>.
+  def raise_on_error(response_xml)
+    if @error_code && !@error_code.empty? &&  @error_code != "0000" then
+
+      # It is important to create the exception with self.class.new and not only BasicResponse.new
+      # This is because this method can be also invoked from a subclass. If a VoiceCallResponse object for example
+      # raises an exception you will receive "VoiceCallResponse" from self.class. This is very important because
+      # only the VoiceCallResponse knows that in this case the response code is called <tt>status</tt>.
+      # This is because there is an inconsistency within the different service responses. 
+      raise(ServiceException.new( self.class.new(response_xml, false) ), "The developer garden service you invoked responded with an error: " + @error_message.to_s)
+    end
+  end
+end

data/lib/basic_service.rb

@@ -0,0 +1,88 @@
+require 'rubygems'
+gem 'troelskn-handsoap'
+
+require 'handsoap'
+require File.dirname(__FILE__) + '/common/xml_tools'
+require File.dirname(__FILE__) + '/service_environment'
+
+# Implements basic logic used by developer garden ruby service implementations.
+class BasicService < Handsoap::Service
+  
+  @@SERVICE_ID = "https://odg.t-online.de"
+
+  # Create some namespaces
+  on_create_document do |doc|
+    doc.alias 'ns1', "http://sts.idm.telekom.com/schema/"
+    doc.alias 'xmlns:ns2', "Security"
+  end                     
+
+  # Constructor
+  # ===Parameters
+  # <tt>username</tt>:: Username, such as myuser@t-online.de
+  # <tt>password</tt>:: Password
+  # <tt>environment</tt>:: Service environment as defined in ServiceEnvironment
+  def initialize(username, password, environment = ServiceEnvironment.SANDBOX)
+    @username = username
+    @password = password
+    @environment = environment
+  end
+
+  protected
+
+  # After being successfully authenticated service calls need to performed including the security token(s) in its soap
+  # headers. This method builds such a header.
+  #
+  # The header of the given document will be enhanced so there is no need to
+  # process the returning value.
+  #
+  # ===Parameters
+  # <tt>doc</tt>:: Request XmlMason document.
+  # <tt>security_token</tt>:: Security tokens as plain text gathered using the TokenService.
+  def build_service_header(doc, security_token)
+    header = build_security_header_common(doc)
+    security = header.find("Security")
+    security.set_value( security_token, :raw)
+    return header
+  end
+
+  # Regardless to whether it is a <tt>login</tt>, <tt>getTokens</tt> or a regular service call there always
+  # has to be a security header. This method provides the structure which is in common to all these method calls.
+  #
+  # The header of the given document will be enhanced so there is no need to
+  # process the returning value.
+  # ===Parameters
+  # <tt>doc</tt>:: Request XmlMason document.  
+  def build_security_header_common(doc)
+    
+    # Get the header element
+    header = doc.find('Header')
+
+    # Add plain security element
+    header.add('Security')
+
+    # Find security element for further enhancement
+    security = header.find('Security')
+
+    # Set namespace
+    security.set_attr("xmlns", "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd")
+    security.set_attr("env:mustUnderstand", "1")
+    return header
+  end
+
+
+  # Extracts any token from the response and returns it.
+  # ===Parameters
+  # <tt>response</tt>:: Response as returned from a <tt>getTokens</tt> call, for example.
+  #
+  # ==Return
+  # Returns the security token as plain text to be inserted into a security header build with <tt>build_security_header_common</tt>. 
+  def get_token_data_from_response(response)
+
+    # nokogiri document. Unfortunately it is unable to parse the returning xml completely.
+    # Especially the body is not parsed completely.
+    doc = response.document
+    intermediate_token = doc.xpath("//schema:tokenData", "schema" => 'http://sts.idm.telekom.com/schema/').inner_text
+
+    return intermediate_token
+  end
+end

data/lib/common/xml_tools.rb

@@ -0,0 +1,25 @@
+module Common
+
+  # Some tools facilitating xml processing.
+  class XmlTools
+
+    # Get rid of surrounding cdata sections.
+    # Attention: This method will modify the given string itself.
+    # ===Parameter
+    # <tt>xml_with_cdata</tt>:: Some xml string with a cdata section.
+    def self.strip_cdata!(xml_with_cdata)
+      xml_with_cdata.gsub!('<![CDATA[', '')
+      xml_with_cdata.gsub!(']]>', '')
+      return xml_with_cdata
+    end
+
+    # Get rid of surrounding cdata sections.
+    # ===Parameter
+    # <tt>xml_with_cdata</tt>:: Some xml string with a cdata section.
+    def self.strip_cdata(xml_with_cdata)
+      xml_with_cdata.gsub('<![CDATA[', '')
+      xml_with_cdata.gsub(']]>', '')
+      return xml_with_cdata
+    end
+  end
+end

data/lib/quota_service/quota_information.rb

@@ -0,0 +1,36 @@
+require File.dirname(__FILE__) + '/../basic_response'
+
+module QuotaService
+
+  # Representing the response of a <tt>get_quota_information</tt>-Call.  
+  class QuotaInformation < BasicResponse
+    attr_accessor :error_code, :error_message, :max_quota, :max_user_quota, :quota_level
+
+    # Constructor.
+    # ===Parameters
+    # <tt>response_xml</tt>:: Xml as returned by a <tt>call_status</tt>-method call.
+    # <tt>raise_exception_on_error</tt>:: Xml as returned by a <tt>call_status</tt>-method call.
+    def initialize(response_xml, raise_exception_on_error = true)
+      super(response_xml)
+
+      doc = response_xml.document
+      @max_quota       = doc.xpath("//maxQuota").text
+      @max_user_quota  = doc.xpath("//maxUserQuota").text
+      @quota_level     = doc.xpath("//quotaLevel").text
+
+      raise_on_error(response_xml) if raise_exception_on_error
+    end
+
+    def max_quota
+      @max_quota.to_i
+    end
+
+    def max_user_quota
+      @max_user_quota.to_i
+    end
+
+    def quota_level
+      @quota_level.to_i
+    end
+  end
+end

data/lib/quota_service/quota_service.rb

@@ -0,0 +1,53 @@
+require File.dirname(__FILE__) + '/../authenticated_service'
+require File.dirname(__FILE__) + '/../quota_service/quota_information'
+
+Handsoap.http_driver = :httpclient
+
+# Print http and soap requests and reponses if ruby has been started with -d option. 
+Handsoap::Service.logger = $stdout if $DEBUG
+
+module QuotaService
+
+  # Client to access the developer garden quota service.
+  #
+  # See also:
+  # * https://www.developergarden.com/openapi/dokumentation/uebergreifende_informationen#2.5.
+  # * https://www.developergarden.com/openapi/dokumentation/services#4.2.6.  
+  class QuotaService < AuthenticatedService
+
+    @@QUOTA_SERVICE_ENDPOINT = {
+      :uri => "https://gateway.developer.telekom.com/p3gw-mod-odg-admin/services/ODGBaseUserService",
+      :version => 1
+    }
+
+    endpoint @@QUOTA_SERVICE_ENDPOINT
+
+    # Get the amount of remaining quota points.
+    # ===Parameters
+    # <tt>module_id</tt>:: module_id of the service for which a quota request to be made, such as "VoiceButlerProduction"
+    def get_quota_information(module_id = "VoiceButlerSandbox")
+
+      response = invoke_authenticated("getQuotaInformation") do |message, doc|
+        message.add('moduleId', module_id)
+      end
+
+      quota_info = QuotaInformation.new(response)
+
+      return quota_info
+    end
+
+    # Changes the quota for a particular service
+    # ===Parameters
+    # <tt>module_id</tt>:: module_id of the service for which a quota request to be made, such as "VoiceButlerProduction"
+    # <tt>quota_max</tt>:: Quota limit to be set
+    def change_quota_pool(module_id = "VoiceButlerSandbox", quota_max = 100)
+
+      response = invoke_authenticated("changeQuotaPool") do |message, doc|
+        message.add('moduleId', module_id)
+        message.add('quotaMax', quota_max)
+      end
+
+      return BasicResponse.new(response)
+    end
+  end
+end

data/lib/service_environment.rb

@@ -0,0 +1,21 @@
+# Possible environment variables to choose a specific service environment.
+#
+# See also: https://www.developergarden.com/openapi/dokumentation/ansprache_der_services_ueber_webservice_schnittstellen#A.1.
+class ServiceEnvironment
+
+  # Production environment constant
+  def self.PRODUCTION    
+    @@PRODUCTION  = 1
+  end
+
+  # Sandbox environment constant
+  def self.SANDBOX
+
+    @@SANDBOX     = 2
+  end
+
+  # Mock environment constant
+  def self.MOCK
+    @@MOCK        = 3
+  end
+end

data/lib/service_exception.rb

@@ -0,0 +1,8 @@
+# Represents a negative service response
+class ServiceException < Exception
+  attr_accessor :response
+
+  def initialize(response)
+    @response = response
+  end 
+end

data/lib/sms_service/sms_response.rb

@@ -0,0 +1,19 @@
+require File.dirname(__FILE__) + '/../basic_response'
+
+# Representing a response from the <tt>SmsService</tt>.
+class SmsResponse < BasicResponse
+
+  # Constructor.
+  # ===Parameters
+  # <tt>response_xml</tt>:: Xml as returned by a <tt>sms_status</tt>-method call.
+  # <tt>raise_exception_on_error</tt>:: Xml as returned by a <tt>sms_status</tt>-method call.
+  def initialize(response_xml, raise_exception_on_error = true)
+    doc = response_xml.document
+
+    @error_code      = doc.xpath("//status").text
+    @error_message   = doc.xpath("//description").text
+
+    raise_on_error(response_xml) if raise_exception_on_error
+  end
+
+end

data/lib/sms_service/sms_service.rb

@@ -0,0 +1,86 @@
+require File.dirname(__FILE__) + '/../authenticated_service'
+require File.dirname(__FILE__) + '/../sms_service/sms_response'
+
+Handsoap.http_driver = :httpclient
+
+# Print http and soap requests and reponses if ruby has been started with -d option.
+Handsoap::Service.logger = $stdout if $DEBUG
+
+module SmsService
+
+  # Client to the developer garden sms service.
+  # Can be used to send sms and flash sms.
+  #
+  # See also:
+  # * https://www.developergarden.com/openapi/dokumentation/services#4.2.3.
+  class SmsService < AuthenticatedService
+
+    @@SMS_SERVICE_ENDPOINT = {
+            :uri => "https://gateway.developer.telekom.com/p3gw-mod-odg-sms/services/SmsService",
+            :version => 1
+    }
+
+    endpoint @@SMS_SERVICE_ENDPOINT
+
+    # Send a sms.
+    # Detailed information about sending of sms can be found under:
+    # * https://www.developergarden.com/openapi/dokumentation/services#4.2.3.
+    # ===Parameters
+    # <tt>numbers</tt>:: Up to 10 receivers can be specified separated by commas (",").
+    # <tt>sms_message</tt>:: Actual message. Can be up to 765 characters. A sms will be charged for each 153 chars.
+    # <tt>originator</tt>:: String to be displayed as the originator of the message.
+    # Max. 11 characters. Further chars will be cut of. Allowed chars are [a-zA-Z0-9].
+    # <tt>environment</tt>:: Service environment as defined in ServiceEnvironment.
+    # <tt>account</tt>:: Currently unused
+    def send_sms(numbers, sms_message, originator, environment = 2, account = "")
+      return send_sms_common("sendSMS", numbers, sms_message, originator, environment, account)
+    end
+
+    # Send a flasg sms. A flash sms goes directly to the handy screen.
+    # Detailed information about sending of sms can be found under:
+    # * https://www.developergarden.com/openapi/dokumentation/services#4.2.3.
+    # ===Parameters
+    # <tt>numbers</tt>:: Up to 10 receivers can be specified separated by commas (",").
+    # <tt>sms_message</tt>:: Actual message. Can be up to 765 characters. A sms will be charged for each 153 chars.
+    # <tt>originator</tt>:: String to be displayed as the originator of the message.
+    # Max. 11 characters. Further chars will be cut of. Allowed chars are [a-zA-Z0-9].
+    # At least one letter needs to be present.
+    # <tt>environment</tt>:: Service environment as defined in ServiceEnvironment.
+    # <tt>account</tt>:: Currently unused
+    def send_flash_sms(numbers, sms_message, originator, environment = 2, account = "")
+      return send_sms_common("sendFlashSMS", numbers, sms_message, originator, environment, account)
+    end
+
+
+    protected
+
+    # Methods sendSMS and sendFlashSMS have identical arguments. They only differ in their action name.
+    # ===Parameters
+    # <tt>numbers</tt>:: Up to 10 receivers can be specified separated by commas (",").
+    # <tt>sms_message</tt>:: Actual message. Can be up to 765 characters. A sms will be charged for each 153 chars.
+    # <tt>originator</tt>:: String to be displayed as the originator of the message.
+    # Max. 11 characters. Further chars will be cut of. Allowed chars are [a-zA-Z0-9].
+    # <tt>environment</tt>:: Service environment as defined in ServiceEnvironment.
+    # <tt>account</tt>:: Currently unused
+    def send_sms_common(action_name, numbers, sms_message, originator, environment = 2, account = "")
+
+      # Cut originator down to 11 characters
+      originator = originator[0, 11]
+
+      response = invoke_authenticated(action_name) do |message, doc|
+        message.add("request")
+        request = message.find("request")
+        request.add('environment', environment)
+        request.add('number', numbers)
+        request.add('message', sms_message)
+        request.add('originator', originator)
+        request.add('account', account)
+      end
+
+      return SmsResponse.new(response)
+    end
+
+
+  end
+
+end

data/lib/telekom_sdk.rb

@@ -0,0 +1,15 @@
+$:.unshift(File.dirname(__FILE__)) unless
+$:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require File.dirname(__FILE__) + '/quota_service/quota_service'
+require File.dirname(__FILE__) + '/voice_call_service/voice_call_service'
+require File.dirname(__FILE__) + '/sms_service/sms_service'
+
+module QuotaService
+end
+
+module SmsService
+end
+
+module VoiceCallService
+end

data/lib/token_service/security_token_validator.rb

@@ -0,0 +1,46 @@
+require 'nokogiri'
+
+module TokenService
+
+  # Verifies the timestamp of a security token to determine whether the token
+  # is yet or still valid.
+  # This is done to avoid unnecessary 
+  class SecurityTokenValidator
+
+    # Verifies the timestamp of a security token to determine whether the token
+    # is yet or still valid.
+    # This is done to avoid unnecessary
+    # === Parameters
+    # <tt>security_token_xml</tt>:: Security token as plain xml.
+    # === Returns
+    # Boolean indicating whether the security token is yet or still valid.
+    def self.token_valid?(security_token_xml)
+      doc = Nokogiri.XML( security_token_xml )
+      conditions_node_set = doc.xpath("//schema:Conditions", "schema" => 'urn:oasis:names:tc:SAML:2.0:assertion')
+      conditions_elment = conditions_node_set.first
+      not_before = conditions_elment.get_attribute('NotBefore')
+      not_on_or_after = conditions_elment.get_attribute('NotOnOrAfter')
+
+      date_not_before = DateTime.parse(not_before)
+      date_not_on_or_after = DateTime.parse(not_on_or_after)
+
+      # Should be: date_not_before =< now < date_not_on_or_after
+      ret = DateTime.now.between?(date_not_before, date_not_on_or_after)
+          
+      return ret
+    end
+
+    # Verifies the timestamp of a security token to determine whether the token
+    # is yet or still valid.
+    # This is done to avoid unnecessary
+    # === Parameters
+    # <tt>security_token_xml</tt>:: Security token as plain xml.
+    # === Returns
+    # (logical) not token_valid?(security_token_xml)
+    # Returns true if the security token is not valid!
+    def self.token_invalid?(security_token_xml)
+      return !(self.token_valid?(security_token_xml))
+    end
+  end
+
+end

data/lib/token_service/token_service.rb

@@ -0,0 +1,162 @@
+require File.dirname(__FILE__) + '/../basic_service'
+require File.dirname(__FILE__) + '/../token_service/security_token_validator'
+
+Handsoap.http_driver = :httpclient
+
+# Print http and soap requests and reponses if ruby has been started with -d option.
+Handsoap::Service.logger = $stdout if $DEBUG
+
+# Module defining a client to access the security token service.
+module TokenService
+
+  # TokenService client to perform authentication against the security token service.
+  # Authentication is performed in two steps:
+  # 1. Call <tt>login</tt> to gather an intermediate token
+  # 2. Call <tt>getTokens</tt> to gather one or more security token(s).
+  # 3. Call any service method passing the security token(s) along the soap header.
+  # The security token service is an implementation of the OASIS WSS specification.
+  # See also: http://www.oasis-open.org/committees/wss/.
+  #
+  # Be aware that all security information is provided in the soap header not in the soap body.
+  # This is why a wss enabled service does not provide a separate method parameter to pass the security tokens.
+  # As mentioned before security is passed in the soap header, instead.
+  #   
+  class TokenService < BasicService
+
+    @@TOKEN_SERVICE_ENDPOINT = {
+            :uri => 'https://sts.idm.telekom.com/TokenService',
+            :version => 1
+    }
+
+    endpoint @@TOKEN_SERVICE_ENDPOINT
+
+    # This is disabled per default because client time and server time need to be in sync
+    # to use this function. Otherwise local token verification might fail even on valid tokens.
+    # This would imply an unnecessary call to the token service.
+    @@PERFORM_LOCAL_TOKEN_CHECKS = false
+
+    # Create some namespace attributes 
+    on_create_document do |doc|
+
+      # doc is of type XmlMason::Document
+      doc.alias 'ns1', "http://stss.idm.telekom.com/schema/"
+      doc.alias 'xmlns:ns2', "Security"
+    end
+
+    # Call the the security token service to gather an intermediate token.
+    def login
+      response = invoke("login") do |message|
+        doc = message.document
+
+        # Build the login header
+        build_login_header(doc)
+      end
+
+      intermediate_token = get_token_data_from_response(response)
+
+      return intermediate_token
+    end
+
+    #### Composite methods
+
+    # Check whether there is a security token. Authenticate if not.
+    # Reauthenticates if the security token has expired.
+    # ===Returns
+    # Security token as plain text/xml.
+    def get_security_token
+
+      # Reauthenticates if the security token has expired.
+      if @security_token.nil? then
+        authenticate
+      end
+
+      # Look at the validity dates of the token and locally check whether the token is still valid.
+      if @@PERFORM_LOCAL_TOKEN_CHECKS && SecurityTokenValidator.token_invalid?(@security_token) then
+        authenticate
+      end
+
+      return @security_token
+    end
+
+    protected
+
+        # Performs a two step authentication gathering an intermediate token and then the actual security token.
+    # The security token is used to make further service calls.
+    # ===Returns
+    # Security token as plain text/xml.
+    def authenticate
+      intermediate_token = login
+      @security_token = get_tokens(intermediate_token)
+
+      return @security_token
+    end
+
+        # Invokes the getTokens method using an intermediate token to gather security token(s).
+    # Security tokens are needed to perform further service calls.
+    # ===Parameters
+    # <tt>intermediate_token</tt>:: Intermediate token gathered by invoking the <tt>login</tt>-Method
+    def get_tokens(intermediate_token)
+      response = invoke("getTokens") do |message|
+        doc = message.document
+
+        # Build the login header
+        build_get_tokens_header(doc, intermediate_token)
+
+        message.add('ns1:serviceId', @@SERVICE_ID)
+      end
+
+      security_token = get_token_data_from_response(response)
+
+      return security_token
+    end
+
+    # Builds the header including the username/password token
+    # to call the login method in order to gather an intermediate token.
+    #
+    # The header of the given document will be enhanced so there is no need to
+    # process the returning value.
+    # ===Parameters
+    # <tt>doc</tt>:: Request XmlMason document.
+    def build_login_header(doc)
+
+      # Get the header element
+      header = build_security_header_common(doc)
+
+      security = header.find('Security')
+      security.add("UsernameToken")
+
+      # Create username section
+      username_token = security.find("UsernameToken")
+      username_token.add("Username")
+      username = username_token.find("Username")
+      username.set_value(@username)
+
+      # Create password section
+      username_token.add("Password")
+      password = username_token.find("Password")
+      password.set_attr("Type", "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText")
+      password.set_value(@password)
+
+      return header
+    end
+
+    # Build the header using the intermediate_token to gather the security token(s).
+    # This is part of the authentication process.
+    #
+    # The header of the given document will be enhanced so there is no need to
+    # process the returning value.
+    # ==Parameter
+    # <tt>doc</tt>:: Request XmlMason document.
+    # <tt>intermediate_token</tt>:: Intermediate token gathered by invoking the <tt>login</tt>-Method
+    def build_get_tokens_header(doc, intermediate_token)
+
+      # Get the header element
+      header = build_security_header_common(doc)
+      security = header.find("Security")
+      security.set_value( intermediate_token, :raw )
+
+      return header
+    end
+
+  end
+end

data/lib/voice_call_service/call_status_response.rb

@@ -0,0 +1,31 @@
+require File.dirname(__FILE__) + '/../basic_response'
+
+# Represents a response for a voice call operation, such as <tt>new_call</tt> ot the
+# VoiceCallService.
+class CallStatusResponse < BasicResponse
+
+  attr_accessor :connection_time_a, :connection_time_b, :description_a, :description_b, :reason_a, :reason_b
+  attr_accessor :state_a, :state_b
+
+  # Constructor.
+  # ===Parameters
+  # <tt>response_xml</tt>:: Xml as returned by a <tt>call_status</tt>-method call.
+  # <tt>raise_exception_on_error</tt>:: Xml as returned by a <tt>call_status</tt>-method call.
+  def initialize(response_xml, raise_exception_on_error = true)
+    doc = response_xml.document
+
+    @error_code      = doc.xpath("//status").text
+    @error_message   = doc.xpath("//err_msg").text
+    @session_id      = doc.xpath("//sessionId").text
+    @connection_time_a = doc.xpath("//connectiontimea").text
+    @connection_time_b = doc.xpath("//connectiontimeb").text
+    @description_a = doc.xpath("//descriptiona").text
+    @description_b = doc.xpath("//descriptionb").text
+    @reason_a = doc.xpath("//reasona").text
+    @reason_b = doc.xpath("//reasonb").text
+    @state_a = doc.xpath("//statea").text
+    @state_b = doc.xpath("//stateb").text
+
+    raise_on_error(response_xml) if raise_exception_on_error
+  end
+end

data/lib/voice_call_service/voice_call_response.rb

@@ -0,0 +1,22 @@
+require File.dirname(__FILE__) + '/../basic_response'
+
+# Represents a response for a voice call operation, such as <tt>new_call</tt> ot the
+# VoiceCallService.
+class VoiceCallResponse < BasicResponse
+
+  attr_accessor :session_id
+
+  # Constructor.
+  # ===Parameters
+  # <tt>response_xml</tt>:: Xml as returned by a <tt>call_status</tt>-method call.
+  # <tt>raise_exception_on_error</tt>:: Xml as returned by a <tt>call_status</tt>-method call.
+  def initialize(response_xml, raise_exception_on_error = true)
+    doc = response_xml.document
+
+    @error_code      = doc.xpath("//status").text
+    @error_message   = doc.xpath("//err_msg").text
+    @session_id      = doc.xpath("//sessionId").text
+    
+    raise_on_error(response_xml) if raise_exception_on_error
+  end
+end

data/lib/voice_call_service/voice_call_service.rb

@@ -0,0 +1,137 @@
+require File.dirname(__FILE__) + '/../authenticated_service'
+require File.dirname(__FILE__) + '/../service_environment'
+require File.dirname(__FILE__) + '/../voice_call_service/voice_call_response'
+require File.dirname(__FILE__) + '/../voice_call_service/call_status_response'
+
+Handsoap.http_driver = :httpclient
+
+# Print http and soap requests and reponses if ruby has been started with -d option.
+Handsoap::Service.logger = $stdout if $DEBUG
+
+module VoiceCallService
+
+  # Establish voice calls between two participants
+  # See also: http://www.developergarden.com/openapi/dokumentation/services#4.2.1.
+  class VoiceCallService < AuthenticatedService
+    @@VOICE_CALL_SERVICE_ENDPOINT = {
+            :uri => "https://gateway.developer.telekom.com/p3gw-mod-odg-voicebutler/services/VoiceButlerService",
+            :version => 1
+    }
+
+    endpoint @@VOICE_CALL_SERVICE_ENDPOINT
+
+    # Establish a voice call between two participants.
+    # After a connection to the first participant has been successfully established the seccond particiant is called.
+    # The call is established after the 2nd participant has picked up.
+    #
+    # ===Parameters
+    # <tt>a_number</tt>:: Phone number of participant a.
+    # <tt>b_number</tt>:: Phone number of participant b.
+    # <tt>expiration</tt>:: Nr of seconds until the call will be canceled if no <tt>call_status</tt> call is received.
+    # <tt>max_duration</tt>:: Maximum duration of the call in secons. In addition to this the system limit is applied.
+    # <tt>environment</tt>:: Service environment as defined in ServiceLevel.
+    # <tt>privacy_a</tt>:: Whether to show the phone number of participant a.
+    # <tt>privacy_b</tt>:: Whether to show the phone number of participant b.
+    # <tt>greeter</tt>:: Currently unused
+    # <tt>account</tt>:: Currently unused
+    def new_call(a_number, b_number, expiration, max_duration, environment = ServiceEnvironment.MOCK, privacy_a = false, privacy_b = false, greeter = "", account = "")
+      response = invoke_authenticated("newCall") do |message, doc|
+        message.add("request")
+        request = message.find("request")
+        request.add('environment', environment)
+        request.add('aNumber', a_number)
+        request.add('bNumber', b_number)
+        request.add('privacyA', privacy_a.to_s)
+        request.add('privacyB', privacy_b.to_s)
+        request.add('expiration', expiration)
+        request.add('maxDuration', max_duration)
+        request.add('greeter', greeter)
+        request.add('account', account)
+      end
+
+      return VoiceCallResponse.new(response)
+    end
+
+    # Retrieve information about a specific call.
+    # ===Parameters
+    # <tt>session_id</tt>:: Session id of the call of interest.
+    # <tt>environment</tt>:: Service environment as defined in ServiceEnvironment.
+    # <tt>keep_alive</tt>:: Prevent an expiration of the call by calling <tt>call_status</tt> with <tt>keep_alive = 1</tt>.
+    def call_status(session_id, environment = ServiceEnvironment.MOCK, keep_alive = 1)
+      response = invoke_authenticated("callStatus") do |message, doc|
+        message.add("request")
+        request = message.find("request")
+        request.add('environment', environment)
+        request.add('keepAlive', keep_alive)
+        request.add('sessionId', session_id)
+      end
+
+      return CallStatusResponse.new(response)
+    end
+
+    # Cancels an ongoing call.
+    # ===Parameters
+    # <tt>session_id</tt>::
+    # <tt>environment</tt>::  Service environment as defined in ServiceEnvironment.
+    def teardown_call(session_id, environment = ServiceEnvironment.MOCK)
+      response = invoke_authenticated("tearDownCall") do |message, doc|
+
+        # Add namespace
+        tdc = message.find("tearDownCall")
+        tdc.set_attr("xmlns", "http://webservice.voicebutler.odg.tonline.de")
+
+        message.add("request")
+        request = message.find("request")
+        request.add('environment', environment)
+        request.add('sessionId', session_id)
+      end
+
+      return CallStatusResponse.new(response)
+    end
+
+    # Establishes a voice call similar to <tt>newCall</tt>. <tt>b_number</tt> can be an array of numbers.
+    # The service will call participants listed in <tt>b_number</tt> in sequence until sb. picks up.
+    # ===Parameters
+    # <tt>a_number</tt>:: Phone number of participant a.
+    # <tt>b_number</tt>:: Phone number(s) of participant b. <tt>b_number</tt> can be an array of strings
+    #     representing numbers or a single string representing a single number.
+    # <tt>expiration</tt>:: Nr of seconds until the call will be canceled if no <tt>call_status</tt> with keepalive=true call is received.
+    # <tt>max_duration</tt>:: Maximum duration of the call in secons. In addition to this the system limit is applied.
+    # <tt>environment</tt>:: Service environment as defined in ServiceEnvironment.
+    # <tt>privacy_a</tt>:: Whether to show the phone number of participant a.
+    # <tt>privacy_b</tt>:: Whether to show the phone number of participant b.
+    # <tt>max_wait</tt>:: Call the next participant after max_wait seconds.   
+    # <tt>greeter</tt>:: Currently unused.
+    # <tt>account</tt>:: Currently unused.
+    def new_call_sequenced(a_number, b_number, expiration, max_duration, environment = ServiceEnvironment.MOCK, privacy_a = false, privacy_b = false, max_wait = 60, greeter = "", account = "")
+      response = invoke_authenticated("newCallSequenced") do |message, doc|
+        message.add("request")
+        request = message.find("request")
+        request.add('environment', environment)
+        request.add('aNumber', a_number)
+
+        # b_number can be an array of strings representing numbers or a single string representing a single number.
+        if b_number.is_a? Array then
+          # It's an array
+          for bn in b_number do
+            request.add('bNumber', bn)
+          end
+        else
+
+          # We assume its a string
+          request.add('bNumber', b_number)
+        end
+
+        request.add('privacyA', privacy_a.to_s)
+        request.add('privacyB', privacy_b.to_s)
+        request.add('expiration', expiration)
+        request.add('maxDuration', max_duration)
+        request.add('maxWait', max_wait)
+        request.add('greeter', greeter)
+        request.add('account', account)
+      end
+
+      return VoiceCallResponse.new(response)
+    end
+  end
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification 
+name: developergarden_sdk
+version: !ruby/object:Gem::Version 
+  version: 0.0.8
+platform: ruby
+authors: 
+- Julian Fischer / Aperto move GmbH
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-08-04 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: httpclient
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        version: 2.1.4
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: nokogiri
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.3.1
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: troelskn-handsoap
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        version: 0.2.8
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: htmlentities
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 4.0.0
+    version: 
+description: Offers a ruby client for the open development services such as send SMS, voice call and quota management of the Deutsche Telekom AG. See also http://www.developergarden.com.
+email: ruby@developergarden.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- LICENSE
+files: 
+- LICENSE
+- README
+- Rakefile
+- lib/authenticated_service.rb
+- lib/basic_response.rb
+- lib/basic_service.rb
+- lib/common
+- lib/common/xml_tools.rb
+- lib/quota_service
+- lib/quota_service/quota_information.rb
+- lib/quota_service/quota_service.rb
+- lib/service_environment.rb
+- lib/service_exception.rb
+- lib/sms_service
+- lib/sms_service/sms_response.rb
+- lib/sms_service/sms_service.rb
+- lib/telekom_sdk.rb
+- lib/token_service
+- lib/token_service/security_token_validator.rb
+- lib/token_service/token_service.rb
+- lib/voice_call_service
+- lib/voice_call_service/call_status_response.rb
+- lib/voice_call_service/voice_call_response.rb
+- lib/voice_call_service/voice_call_service.rb
+has_rdoc: true
+homepage: http://www.developergarden.com
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.1
+signing_key: 
+specification_version: 2
+summary: Offers a ruby client for the open development services such as send SMS, voice call and quota management of the Deutsche Telekom AG. See also http://www.developergarden.com.
+test_files: []
+