developergarden_sdk 0.9.1 → 0.9.2

data/README

@@ -1,147 +1 @@
-== 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.
-
-
-=== Installation
- sudo gem install developergarden_sdk
-
-Dependent gems will be installed automatically.
-
-=== 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, "")
-
-
-=== Ruby Example to perform an ip location request
-
- require 'rubygems'
- gem 'developergarden_sdk'
- require 'token_service/token_service'
- require 'ip_location_service/ip_location_service'
-
- @ip_location_service = IpLocationService::IpLocationService.new("<USER>@t-online.de", "<PASSWORD>")
-
- ip = IpLocationService::IpAddress.new("93.222.255.58")
- response = @ip_location_service.locate_ip(ip, ServiceEnvironment.PRODUCTION)
-
- puts response.ip_address_locations.first.address
- puts response.ip_address_locations.first.is_in_region.country_code
- puts response.ip_address_locations.first.is_in_region.region_name
-
- # If you except a single ip location (if you have passed a single ip to look up)
- # then you can use the following way to access the location
- puts response.ip_address_location.address
- puts response.ip_address_location.is_in_region.country_code
- puts response.ip_address_location.is_in_region.region_name
-
-=== Ruby Example to perform a local search
- require 'rubygems'
- gem 'developergarden_sdk'
- require 'token_service/token_service'
- require 'token_service/token_service'
- require 'local_search_service/local_search_service'
-
- @service = LocalSearchService::LocalSearchService.new("<USER>@t-online.de", "<PASSWORD>")
-
- search_parameter = {
-   :what => "music",
-   :near => "Konstanz"
- }
- response = @service.local_search(search_parameter, ServiceEnvironment.PRODUCTION)
-
- # Show response xml
- puts response.search_result.to_xml
- results_where_locs_where = response.search_result.xpath("//RESULTS/WHERE_LOCS/WHERE").first
- lat = results_where_locs_where["LAT"]
- puts lat
-
-=== Ruby Example to create a conference call
- require 'rubygems'
- gem 'developergarden_sdk'
- require 'token_Service/token_service'
- require 'conference_call_service/conference_call_service'
-
- environment = ServiceEnvironment.PRODUCTION
-
- service = ConferenceCallService::ConferenceCallService.new("<USERNAME>@t-online.de", "<PASSWORD>")
-
- conf_details = ConferenceCallService::ConferenceDetails.new("A very important conf", "A very impressive description", 30)
-
- response = service.create_conference("max.mustermann", conf_details, nil, environment)
-
- conf_id = response.conference_id
-
- participant = ConferenceCallService::ParticipantDetails.new('maxi', 'max', '<NUMBER A>', 'max@spin.to', 1)
- participant2 = ConferenceCallService::ParticipantDetails.new('roger', 'beep', '<NUMBER B>', 'roger@spin.to', 0)
-
- service.new_participant(conf_id, participant, environment)
- service.new_participant(conf_id, participant2, environment)
-
- service.commit_conference(conf_id, 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.
-
-
-==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.
+See README.rdoc

data/Rakefile

@@ -13,11 +13,11 @@ require 'fileutils'
 
 spec = Gem::Specification.new do |s|
   s.name = 'developergarden_sdk'
-  s.version = '0.9.1'
+  s.version = '0.9.2'
   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.summary = 'Client library for the open development services of Deutsche Telekom AG. The services are: send SMS, voice call, conference call, IP location, local search and quota management. For more information, please see http://www.developergarden.com.'
   s.description = s.summary
   s.author = 'Julian Fischer / Aperto move GmbH'
   s.email = 'ruby@developergarden.com'

data/lib/quota_service/account_balance_response.rb

@@ -0,0 +1,49 @@
+class AccountBalanceResponse < BasicResponse
+  attr_accessor :account_balances
+
+  # 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("//errorCode").to_s
+    @error_message    = doc.xpath("//errorMessage").to_s
+    @account_balances = []
+
+    # Get a list of all account sections
+    accounts_xml = doc.xpath("//getAccountBalanceResponse/Account")
+
+    # Create Account objects out of the xml response
+    if accounts_xml.is_a?(Handsoap::XmlQueryFront::NodeSelection) then
+      accounts_xml.each do |account_xml|
+        account = Account.build_from_xml(account_xml)        
+        account_balances << account        
+      end
+    else
+      raise "Unexpected response format."
+    end
+
+    raise_on_error(response_xml) if raise_exception_on_error
+  end
+end
+
+class Account
+  attr_accessor :account, :credits
+
+  def initialize(account, credits)
+    @account = account
+    @credits = credits
+  end
+
+  def self.build_from_xml(xml_doc)    
+    account = xml_doc.xpath("Account").to_s
+    credits = xml_doc.xpath("Credits").to_s
+    return Account.new(account, credits)
+  end
+
+  def to_s
+    self.inspect
+  end
+end

data/lib/quota_service/quota_service.rb

@@ -1,5 +1,6 @@
 require File.dirname(__FILE__) + '/../authenticated_service'
 require File.dirname(__FILE__) + '/../quota_service/quota_information'
+require File.dirname(__FILE__) + '/../quota_service/account_balance_response'
 
 Handsoap.http_driver = :httpclient
 
@@ -26,13 +27,11 @@ module QuotaService
     # ===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
 
@@ -41,7 +40,6 @@ module QuotaService
     # <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)
@@ -49,5 +47,17 @@ module QuotaService
 
       return BasicResponse.new(response)
     end
+
+    # Get balance of the given developergarden account.
+    # ===Parameters
+    # <tt>account</tt>:: Account ids of the sub accounts to retrieve the balance for.
+    #   Retrieves the balance of the main account if the account balance is empty.
+    def get_account_balance(account = nil)
+      response = invoke_authenticated("getAccountBalance") do |message, doc|
+        message.add('account', account) if account        
+      end
+
+      return AccountBalanceResponse.new(response)
+    end
   end
 end

data/lib/sms_service/sms_get_validated_numbers_response.rb

@@ -0,0 +1,52 @@
+require File.dirname(__FILE__) + '/../basic_response'
+
+# Representing a response from the <tt>SmsService</tt>.
+class SmsGetValidatedNumbersResponse < BasicResponse
+
+  attr_accessor :validated_numbers
+
+  # 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("//statusCode").to_s
+    @error_message   = doc.xpath("//statusMessage").to_s
+    @validated_numbers = []
+
+    validated_numbers_xml   = doc.xpath("//validatedNumbers")
+
+    if validated_numbers_xml.is_a?(Handsoap::XmlQueryFront::NodeSelection) then
+      validated_numbers_xml.each do |validated_number_xml|
+        validated_number = ValidatedNumber.build_from_xml(validated_number_xml)
+        validated_numbers << validated_number        
+      end
+    else
+      raise "Unexpected response format."
+    end
+    
+    raise_on_error(response_xml) if raise_exception_on_error
+  end
+end
+
+class ValidatedNumber
+  attr_accessor :number, :validated_until
+
+  def initialize(number, validated_until)
+    @number           = number
+    @validated_until  = validated_until
+  end
+
+  def self.build_from_xml(xml_doc)
+    number = xml_doc.xpath("number").to_s
+    validated_until = xml_doc.xpath("validUntil").to_s
+
+    return ValidatedNumber.new(number, validated_until)
+  end
+
+  def to_s
+    self.inspect
+  end
+end

data/lib/sms_service/sms_validation_response.rb

@@ -0,0 +1,18 @@
+require File.dirname(__FILE__) + '/../basic_response'
+
+# Representing a response from the <tt>SmsService</tt>.
+class SmsSendValidationResponse < 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("//statusCode").to_s
+    @error_message   = doc.xpath("//statusMessage").to_s
+
+    raise_on_error(response_xml) if raise_exception_on_error
+  end
+end

data/lib/sms_service/sms_validation_service.rb

@@ -0,0 +1,101 @@
+require File.dirname(__FILE__) + '/../authenticated_service'
+require File.dirname(__FILE__) + '/../sms_service/sms_validation_response'
+require File.dirname(__FILE__) + '/../sms_service/sms_get_validated_numbers_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
+
+  # SmsValidationService allows you to use physical mobile phone numbers as the sender number
+  # of a text message.
+  #
+  # See also:
+  # * https://www.developergarden.com/openapi/dokumentation/services#4.2.3.
+  class SmsValidationService < AuthenticatedService
+
+    @@SMS_VALIDATION_SERVICE_SCHEMA = "http://webservice.sms.odg.tonline.de"
+
+    @@SMS_SERVICE_ENDPOINT = {
+            :uri => "https://gateway.developer.telekom.com/p3gw-mod-odg-sms-validation/services/SmsValidationUserService",
+            :version => 1
+    }
+
+    endpoint @@SMS_SERVICE_ENDPOINT
+
+    # Add namespaces to the handsoap XmlMason document.
+    def on_create_document(doc)
+      super(doc)
+      doc.alias 'smsvs', @@SMS_VALIDATION_SERVICE_SCHEMA
+    end
+
+    # Send a validation text message.
+    # 
+    # Note this method does not support a sandbox service environment.
+    # Validated numbers can be used in both the production and sandbox environment.
+    # For more details please refer to the developergarden docs.
+    # ===Parameters
+    # <tt>message</tt>:: Message which should be send along the validation key. Message needs to contain two
+    #                    placeholders: #key# and #validUntil#.
+    # <tt>number</tt>:: Number to be validated.
+    # <tt>originator</tt>:: Originator to be displayed in the receiver's validation text message.
+    # <tt>account</tt>:: Optional developergarden subaccount.
+    def send_validation_keyword(message, number, originator, environment = ServiceEnvironment.MOCK, account = "")
+      response = invoke_authenticated('smsvs:sendValidationKeywordRequest') do |request, doc|
+        request.add('message', message)
+        request.add('number', number)
+        request.add('originator', originator)        
+        request.add('account', account)
+        request.add('environment', environment)
+      end
+
+      return SmsSendValidationResponse.new(response)
+    end
+
+
+    # Validate the requested number using the received keyword.
+    # ===Parameters
+    # <tt>keyword</tt>:: Secret keyword used to finalize the ongoing validation process. 
+    # <tt>number</tt>:: Number to be validated         
+    # <tt>environment</tt>:: Note that only the MOCK and PRODUCTION environments can be used. Numbers already validated
+    #   in the PRODUCTIOn environment can also be used for sending text messages in the SANDBOX ENVIRONMENT.
+    #   Validations with the keyword <tt>SECRET</tt> in the MOCK environment should always succeed.
+    def validate(keyword, number, environment = ServiceEnvironment.MOCK)
+      response = invoke_authenticated('smsvs:validateRequest') do |request, doc|
+        request.add('keyword', keyword)
+        request.add('number', number)              
+        request.add('environment', environment)
+      end
+
+      return SmsSendValidationResponse.new(response)
+    end
+    
+    # Invalidate the given number.
+    # ===Parameters
+    # <tt>number</tt>:: Number to be invalidated         
+    # <tt>environment</tt>:: Note that only the MOCK and PRODUCTION environments can be used. Numbers already validated
+    #   in the PRODUCTIOn environment can also be used for sending text messages in the SANDBOX ENVIRONMENT.
+    #   Validations with the keyword <tt>SECRET</tt> in the MOCK environment should always succeed.
+    def invalidate(number, environment = ServiceEnvironment.MOCK)
+      response = invoke_authenticated('smsvs:invalidateRequest') do |request, doc|
+        request.add('number', number)              
+        request.add('environment', environment)
+      end
+
+      return SmsSendValidationResponse.new(response)
+    end
+
+    # Retrieves a list of already validated numbers.
+    # ===Parameters     
+    # <tt>environment</tt>:: Note that only the MOCK and PRODUCTION environments can be used.    
+    def get_validated_numbers(environment = ServiceEnvironment.MOCK)
+      response = invoke_authenticated('smsvs:getValidatedNumbersRequest') do |request, doc|                
+        request.add('environment', environment)
+      end
+
+      return SmsGetValidatedNumbersResponse.new(response)
+    end
+  end
+end

data/lib/voice_call_service/call_status_response.rb

@@ -5,7 +5,7 @@ require File.dirname(__FILE__) + '/../basic_response'
 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
+  attr_accessor :state_a, :state_b, :be164, :bindex
 
   # Constructor.
   # ===Parameters
@@ -25,6 +25,9 @@ class CallStatusResponse < BasicResponse
     @reason_b = doc.xpath("//reasonb").to_s
     @state_a = doc.xpath("//statea").to_s
     @state_b = doc.xpath("//stateb").to_s
+    @be164 = doc.xpath("//be164").to_s
+    @bindex = doc.xpath("//bindex").to_s
+
 
     raise_on_error(response_xml) if raise_exception_on_error
   end

data/lib/voice_call_service/voice_call_service.rb

@@ -13,7 +13,7 @@ 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 = {
+    @@VOICE_CALL_SERVICE_ENDPOINT = {                      +
             :uri => "https://gateway.developer.telekom.com/p3gw-mod-odg-voicebutler/services/VoiceButlerService",
             :version => 1
     }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: developergarden_sdk
 version: !ruby/object:Gem::Version 
-  version: 0.9.1
+  version: 0.9.2
 platform: ruby
 authors: 
 - Julian Fischer / Aperto move GmbH
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-12-22 00:00:00 +01:00
+date: 2010-02-09 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -52,7 +52,7 @@ dependencies:
       - !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.
+description: "Client library for the open development services of Deutsche Telekom AG. The services are: send SMS, voice call, conference call, IP location, local search and quota management. For more information, please see http://www.developergarden.com."
 email: ruby@developergarden.com
 executables: []
 
@@ -102,12 +102,16 @@ files:
 - lib/ip_location_service/region.rb
 - lib/local_search_service/local_search_response.rb
 - lib/local_search_service/local_search_service.rb
+- lib/quota_service/account_balance_response.rb
 - lib/quota_service/quota_information.rb
 - lib/quota_service/quota_service.rb
 - lib/service_environment.rb
 - lib/service_exception.rb
+- lib/sms_service/sms_get_validated_numbers_response.rb
 - lib/sms_service/sms_response.rb
 - lib/sms_service/sms_service.rb
+- lib/sms_service/sms_validation_response.rb
+- lib/sms_service/sms_validation_service.rb
 - lib/telekom_sdk.rb
 - lib/token_service/security_token_validator.rb
 - lib/token_service/token_service.rb
@@ -141,6 +145,6 @@ rubyforge_project:
 rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3
-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.
+summary: "Client library for the open development services of Deutsche Telekom AG. The services are: send SMS, voice call, conference call, IP location, local search and quota management. For more information, please see http://www.developergarden.com."
 test_files: []