tp-blather 0.8.2

data/lib/blather/stanza/iq.rb

@@ -0,0 +1,144 @@
+module Blather
+class Stanza
+
+  # # Iq Stanza
+  #
+  # [RFC 3920 Section 9.2.3 - IQ Semantics](http://xmpp.org/rfcs/rfc3920.html#rfc.section.9.2.3)
+  #
+  # Info/Query, or IQ, is a request-response mechanism, similar in some ways
+  # to HTTP. The semantics of IQ enable an entity to make a request of, and
+  # receive a response from, another entity. The data content of the request
+  # and response is defined by the namespace declaration of a direct child
+  # element of the IQ element, and the interaction is tracked by the
+  # requesting entity through use of the 'id' attribute. Thus, IQ interactions
+  # follow a common pattern of structured data exchange such as get/result or
+  # set/result (although an error may be returned in reply to a request if
+  # appropriate).
+  #
+  # ## "ID" Attribute
+  #
+  # Iq Stanzas require the ID attribute be set. Blather will handle this
+  # automatically when a new Iq is created.
+  #
+  # ## "Type" Attribute
+  #
+  # * `:get` -- The stanza is a request for information or requirements.
+  #
+  # * `:set` -- The stanza provides required data, sets new values, or
+  #   replaces existing values.
+  #
+  # * `:result` -- The stanza is a response to a successful get or set request.
+  #
+  # * `:error` -- An error has occurred regarding processing or delivery of a
+  #   previously-sent get or set (see Stanza Errors).
+  #
+  # Blather provides a helper for each possible type:
+  #
+  #     Iq#get?
+  #     Iq#set?
+  #     Iq#result?
+  #     Iq#error?
+  #
+  # Blather treats the `type` attribute like a normal ruby object attribute
+  # providing a getter and setter. The default `type` is `get`.
+  #
+  #     iq = Iq.new
+  #     iq.type               # => :get
+  #     iq.get?               # => true
+  #     iq.type = :set
+  #     iq.set?               # => true
+  #     iq.get?               # => false
+  #
+  #     iq.type = :invalid    # => RuntimeError
+  #
+  # @handler :iq
+  class Iq < Stanza
+    # @private
+    VALID_TYPES = [:get, :set, :result, :error].freeze
+
+    register :iq
+
+    # @private
+    def self.import(node)
+      klass = nil
+      node.children.detect do |e|
+        ns = e.namespace ? e.namespace.href : nil
+        klass = class_from_registration(e.element_name, ns)
+      end
+
+      if klass && klass != self
+        klass.import(node)
+      else
+        new(node[:type]).inherit(node)
+      end
+    end
+
+    # Create a new Iq
+    #
+    # @param [Symbol, nil] type the type of stanza (:get, :set, :result, :error)
+    # @param [Blather::JID, String, nil] jid the JID of the inteded recipient
+    # @param [#to_s] id the stanza's ID. Leaving this nil will set the ID to
+    #                the next unique number
+    def self.new(type = nil, to = nil, id = nil)
+      node = super :iq
+      node.type = type || :get
+      node.to = to
+      node.id = id || self.next_id
+      node
+    end
+
+    # Check if the IQ is of type :get
+    #
+    # @return [true, false]
+    def get?
+      self.type == :get
+    end
+
+    # Check if the IQ is of type :set
+    #
+    # @return [true, false]
+    def set?
+      self.type == :set
+    end
+
+    # Check if the IQ is of type :result
+    #
+    # @return [true, false]
+    def result?
+      self.type == :result
+    end
+
+    # Check if the IQ is of type :error
+    #
+    # @return [true, false]
+    def error?
+      self.type == :error
+    end
+
+    # Ensures type is :get, :set, :result or :error
+    #
+    # @param [#to_sym] type the Iq type. Must be one of VALID_TYPES
+    def type=(type)
+      if type && !VALID_TYPES.include?(type.to_sym)
+        raise ArgumentError, "Invalid Type (#{type}), use: #{VALID_TYPES*' '}"
+      end
+      super
+    end
+
+    # Overrides the parent method to ensure the reply is of type :result and that
+    # all children are removed.
+    #
+    # @param [Hash] opts options to pass to reply!
+    # @option opts [Boolean] :remove_children Wether or not to remove child nodes when replying
+    #
+    # @return [self]
+    def reply!(opts = {})
+      opts = {:remove_children => true}.merge opts
+      super
+      self.type = :result
+      self
+    end
+  end
+
+end
+end

data/lib/blather/stanza/iq/command.rb

@@ -0,0 +1,339 @@
+module Blather
+class Stanza
+class Iq
+
+  # # Command Stanza
+  #
+  # [XEP-0050 Ad-Hoc Commands](http://xmpp.org/extensions/xep-0050.html)
+  #
+  # This is a base class for any command based Iq stanzas. It provides a base set
+  # of methods for working with command stanzas
+  #
+  # @handler :command
+  class Command < Iq
+    # @private
+    VALID_ACTIONS = [:cancel, :execute, :complete, :next, :prev].freeze
+    # @private
+    VALID_STATUS = [:executing, :completed, :canceled].freeze
+    # @private
+    VALID_NOTE_TYPES = [:info, :warn, :error].freeze
+
+    register :command, :command, 'http://jabber.org/protocol/commands'
+
+    # Overrides the parent method to ensure a command node is created
+    #
+    # @param [:get, :set, :result, :error, nil] type the IQ type
+    # @param [String] node the name of the node
+    # @param [:cancel, :execute, :complete, :next, :prev, nil] action the command's action
+    # @return [Command] a new Command stanza
+    def self.new(type = :set, node = nil, action = :execute)
+      new_node = super type
+      new_node.command
+      new_node.node = node
+      new_node.action = action
+      new_node
+    end
+
+    # Overrides the parent method to ensure the current command node is destroyed
+    # and the action is set to execute if no action provided
+    #
+    # @see Blather::Stanza::Iq#inherit
+    def inherit(node)
+      command.remove
+      super
+      self.action = :execute unless self.action
+      self
+    end
+
+    # Overrides the parent method to ensure the reply has no action
+    #
+    # @param [Hash] opts options to pass to reply!
+    # @option opts [Boolean] :remove_children Wether or not to remove child nodes when replying
+    #
+    # @return [self]
+    def reply!(opts = {})
+      super
+      self.action = nil
+      self
+    end
+
+    # Command node accessor
+    # If a command node exists it will be returned.
+    # Otherwise a new node will be created and returned
+    #
+    # @return [Blather::XMPPNode]
+    def command
+      c = if self.class.registered_ns
+        find_first('ns:command', :ns => self.class.registered_ns)
+      else
+        find_first('command')
+      end
+
+      unless c
+        (self << (c = XMPPNode.new('command', self.document)))
+        c.namespace = self.class.registered_ns
+      end
+      c
+    end
+
+    # Get the name of the node
+    #
+    # @return [String, nil]
+    def node
+      command[:node]
+    end
+
+    # Set the name of the node
+    #
+    # @param [String, nil] node the new node name
+    def node=(node)
+      command[:node] = node
+    end
+
+    # Get the sessionid of the command
+    #
+    # @return [String, nil]
+    def sessionid
+      command[:sessionid]
+    end
+
+    # Check if there is a sessionid set
+    #
+    # @return [true, false]
+    def sessionid?
+      !sessionid.nil?
+    end
+
+    # Set the sessionid of the command
+    #
+    # @param [String, nil] sessionid the new sessionid
+    def sessionid=(sessionid)
+      command[:sessionid] = Digest::SHA1.hexdigest(sessionid)
+    end
+
+    # Generate a new session ID (SHA-1 hash)
+    def new_sessionid!
+      self.sessionid = "commandsession-#{id}"
+    end
+
+    # Get the action of the command
+    #
+    # @return [Symbol, nil]
+    def action
+      (val = command[:action]) && val.to_sym
+    end
+
+    # Check if the command action is :cancel
+    #
+    # @return [true, false]
+    def cancel?
+      self.action == :cancel
+    end
+
+    # Check if the command action is :execute
+    #
+    # @return [true, false]
+    def execute?
+      self.action == :execute
+    end
+
+    # Check if the command action is :complete
+    #
+    # @return [true, false]
+    def complete?
+      self.action == :complete
+    end
+
+    # Check if the command action is :next
+    #
+    # @return [true, false]
+    def next?
+      self.action == :next
+    end
+
+    # Check if the command action is :prev
+    #
+    # @return [true, false]
+    def prev?
+      self.action == :prev
+    end
+
+    # Set the action of the command
+    #
+    # @param [:cancel, :execute, :complete, :next, :prev] action the new action
+    def action=(action)
+      if action && !VALID_ACTIONS.include?(action.to_sym)
+        raise ArgumentError, "Invalid Action (#{action}), use: #{VALID_ACTIONS*' '}"
+      end
+      command[:action] = action
+    end
+
+    # Get the status of the command
+    #
+    # @return [Symbol, nil]
+    def status
+      ((val = command[:status]) && val.to_sym) || :executing
+    end
+
+    # Check if the command status is :executing
+    #
+    # @return [true, false]
+    def executing?
+      self.status == :executing
+    end
+
+    # Check if the command status is :completed
+    #
+    # @return [true, false]
+    def completed?
+      self.status == :completed
+    end
+
+    # Check if the command status is :canceled
+    #
+    # @return [true, false]
+    def canceled?
+      self.status == :canceled
+    end
+
+    # Set the status of the command
+    #
+    # @param [:executing, :completed, :canceled] status the new status
+    def status=(status)
+      if status && !VALID_STATUS.include?(status.to_sym)
+        raise ArgumentError, "Invalid Action (#{status}), use: #{VALID_STATUS*' '}"
+      end
+      command[:status] = status
+    end
+
+    # Command actions accessor
+    # If a command actions element exists it will be returned.
+    # Otherwise a new actions element will be created and returned
+    #
+    # @return [Blather::XMPPNode]
+    def actions
+      unless a = self.command.find_first('ns:actions', :ns => self.class.registered_ns)
+        (self.command << (a = XMPPNode.new('actions', self.document)))
+        a.namespace = self.command.namespace
+      end
+      a
+    end
+
+    # Get the command's allowed actions
+    #
+    # @return [Array<Symbol>]
+    def allowed_actions
+      ([:execute] + actions.children.map { |action| action.name.to_sym }).uniq
+    end
+
+    # Get the primary allowed action
+    #
+    # @return [Symbol]
+    def primary_allowed_action
+      (actions[:execute] || :execute).to_sym
+    end
+
+    # Set the primary allowed action
+    #
+    # This must be one of :prev, :next, :complete or :execute
+    #
+    # @param [#to_sym] a the primary allowed action
+    def primary_allowed_action=(a)
+      a = a.to_sym
+      if a && ![:prev, :next, :complete, :execute].include?(a)
+        raise ArgumentError, "Invalid Action (#{a}), use: #{[:prev, :next, :complete, :execute]*' '}"
+      end
+      actions[:execute] = a
+    end
+
+    # Add allowed actions to the command
+    #
+    # @param [[:prev, :next, :complete]] allowed_actions the new allowed actions
+    def allowed_actions=(allowed_actions)
+      allowed_actions = ([allowed_actions].flatten.map(&:to_sym) + [:execute]).uniq
+      if (invalid_actions = allowed_actions - VALID_ACTIONS).size > 0
+        raise ArgumentError, "Invalid Action(s) (#{invalid_actions*' '}), use: #{VALID_ACTIONS*' '}"
+      end
+      actions.children.map(&:remove)
+      allowed_actions.each { |action| actions << XMPPNode.new(action.to_s) }
+    end
+
+    # Remove allowed actions from the command
+    #
+    # @param [[:prev, :next, :complete]] disallowed_actions the allowed actions to remove
+    def remove_allowed_actions!
+      actions.remove
+    end
+
+    # Command note accessor
+    # If a command note exists it will be returned.
+    # Otherwise a new note will be created and returned
+    #
+    # @return [Blather::XMPPNode]
+    def note
+      unless n = self.command.find_first('ns:note', :ns => self.class.registered_ns)
+        (self.command << (n = XMPPNode.new('note', self.document)))
+        n.namespace = self.command.namespace
+      end
+      n
+    end
+
+    # Get the note_type of the command
+    #
+    # @return [Symbol, nil]
+    def note_type
+      (val = note[:type]) && val.to_sym
+    end
+
+    # Check if the command status is :info
+    #
+    # @return [true, false]
+    def info?
+      self.note_type == :info
+    end
+
+    # Check if the command status is :warn
+    #
+    # @return [true, false]
+    def warn?
+      self.status == :warn
+    end
+
+    # Check if the command status is :error
+    #
+    # @return [true, false]
+    def error?
+      self.status == :error
+    end
+
+    # Set the note_type of the command
+    #
+    # @param [:executing, :completed, :canceled] note_type the new note_type
+    def note_type=(note_type)
+      if note_type && !VALID_NOTE_TYPES.include?(note_type.to_sym)
+        raise ArgumentError, "Invalid Action (#{note_type}), use: #{VALID_NOTE_TYPES*' '}"
+      end
+      note[:type] = note_type
+    end
+
+    # Get the text of the command's note
+    def note_text
+      content_from :note
+    end
+
+    # Set the command's note text
+    #
+    # @param [String] note_text the command's new note text
+    def note_text=(note_text)
+      set_content_for :note, note_text
+    end
+
+    # Returns the command's x:data form child
+    def form
+      X.find_or_create command
+    end
+  end #Command
+
+end #Iq
+end #Stanza
+end #Blather