qbfc 0.1.0-x86-mswin32-60

data/lib/qbfc/qb_collection.rb

@@ -0,0 +1,26 @@
+module QBFC
+
+  # A QBCollection object is used as an intermediate object when doing finds,
+  # for example, in <tt>qb_session.customers.find(:all)</tt>, +customers+
+  # returns a QBCollection instance which then is sent the find call.
+  # The instance sends the find method on to the appropriate Class.
+  # The reason for having this intermediate class is to be able to
+  # pass a reference to the Session to the find method
+  # (or other class method).
+  # 
+  # There's probably no reason to use this class directly.
+  class QBCollection
+    
+    # +sess+ is a QBFC::Session object, +class_name+ is the name of
+    # a class descended from QBFC::Base.
+    def initialize(sess, class_name)
+      @sess = sess
+      @klass = QBFC::const_get(class_name)
+    end
+  
+    # Send any missing methods to the class, along with the +Session+ object
+    def method_missing(symbol, *params) #:nodoc:
+      @klass.send(symbol, @sess, *params)
+    end
+  end
+end

data/lib/qbfc/qb_types.rb

@@ -0,0 +1,34 @@
+# This file sets up the classes for QuickBooks entities, transactions and reports.
+
+# Types that allow Query and Delete only
+QBFC_DELETE_ONLY = %w{PayrollItemNonWage DataEventRecoveryInfo}
+
+# Report types return an IReportRet
+QBFC_REPORT_TYPES = %w{AgingReport BudgetSummaryReport CustomDetailReport CustomSummaryReport
+                      GeneralDetailReport GeneralSummaryReport JobReport PayrollDetailReport PayrollSummaryReport TimeReport }
+
+# Types that allow Special adds (Pre-defined and normally added automatically by QuickBooks)
+QBFC_HAS_SPECIAL_ADD = %w{Account Item}
+
+# TODO: Here and below arrays I haven't yet formed any approach to dealing with.
+# I leave them here as a reminder.
+ELEMENTS_ADD_MOD = %w{ DataExt }         
+                    
+ELEMENTS_ADD_MOD_QUERY = %w{ DataExtDef }
+                    
+# Types that have their own DelRq
+ELEMENT_DEL_TYPES = %w{DataEventRecoveryInfo DataExt DataExtDef}
+
+# Query types support Query requests only and return an itemized list of some sort;
+# most of these may be integrated as special finders for their types.
+QBFC_QUERY_TYPES =  %w{BillToPay ListDeleted ReceivePaymentToDeposit Template TxnDeleted SalesTaxPaymentCheck}
+
+QBFC_ANOTHER_TO_INTEGRATE_SOMEWHERE = %w{ ItemAssembliesCanBuild }
+
+
+module QBFC
+  # Create QBElement classes
+  (QBFC_REPORT_TYPES + QBFC_DELETE_ONLY + %w{DataExt DataExtDef}).uniq.each do | qb_element_name |
+    const_set(qb_element_name, Class.new(Base))
+  end
+end

data/lib/qbfc/qbfc_const.rb

@@ -0,0 +1,14 @@
+# QBFC_CONST contains constants defined by QBFC6.QBSessionManager.
+# For example:
+# 
+#   QBFC_CONST::DmToday # => 1 (for DateMacro)
+#   
+# The constants defined in the SDK documents all begin with a lower case letter.
+# In contrast, WIN32OLE capitalizes the constants to follow Ruby naming conventions:
+# 
+#   QBFC_CONST::DmToday instead of QBFC_CONST::dmToday
+
+module QBFC_CONST
+end
+
+WIN32OLE.const_load(WIN32OLE.new('QBFC6.QBSessionManager'), QBFC_CONST)

data/lib/qbfc/request.rb

@@ -0,0 +1,158 @@
+module QBFC
+  # A QBFC::Request handles creating and sending a Request, including creating
+  # the RequestSet. Most often, RubyQBFC classes create and execute the Request
+  # internally, however, the Base.find, for example, accepts a QBFC::Request
+  # object as an argument if greater control is needed.
+  # 
+  # The WIN32OLE Request object is wrapped in OLEWrapper, so Ruby-esque methods
+  # can be used.
+  # 
+  #   req = QBFC::Request.new(qb_session, "CustomerQuery").
+  #     or_customer_list_query.customer_list_filter.max_returned = 2
+  #   puts req.response
+  class Request 
+  
+    # <tt>session</tt> is a QBFC::Session object (or a Session object not created through Ruby QBFC)
+    # <tt>request_type</tt> is the name of the request, not including trailing 'Rq',
+    # e.g. 'CustomerQuery', 'CustomerMod'
+    def initialize(sess, request_type, country = 'US', major_version = 6, minor_version = 0)
+      @sess = sess
+      
+      begin
+        @request_set = sess.CreateMsgSetRequest(country, major_version, minor_version)
+      rescue WIN32OLERuntimeError => error
+        if error.to_s =~ /error code:8004030A/
+          raise QBFC::QBXMLVersionError, "Unsupported qbXML version"
+        else
+          raise
+        end
+      end
+      
+      begin
+        @request = @request_set.send("Append#{request_type}Rq")
+      rescue WIN32OLERuntimeError => error
+        if error.to_s =~ /error code:0x80020006/
+          raise QBFC::UnknownRequestError, "Unknown request name '#{request_type}'"
+        else
+          raise
+        end
+      end
+    end
+    
+    # Submit the requests. This returns the full (not wrapped) response object.
+    def submit
+      @sess.DoRequests(@request_set)
+    end
+    
+    # Submit the Request and return the response Detail, wrapped in OLEWrapper (unless nil).
+    # The response does not include any MsgSetResponse attributes.
+    def response
+      submit.ResponseList.GetAt(0).Detail
+    end
+    
+    # Get the OR*Query object of the given Request
+    # For example, the ORListQuery
+    def query
+      query_name = @request.ole_methods.detect{|m| m.to_s =~ /Query\Z/}
+      return nil if query_name.nil?
+      @request.send(query_name.to_s.to_sym)
+    end
+    
+    # Get the *Filter object of the given Request
+    # For example, the ListFilter
+    def filter
+      q = self.query
+      return nil if q.nil?
+      filter_name = q.ole_methods.detect{|m| m.to_s =~ /Filter\Z/}
+      return nil if filter_name.nil?
+      q.send(filter_name.to_s.to_sym)
+    end
+    
+    # Returns where the filter is available for use. That is, that
+    # none of the query options other than filter have been used
+    def filter_available?
+      # -1 = unused, 2 = Filter used
+      self.query.ole_object.ortype == -1 ||
+        self.query.ole_object.ortype == 2
+    end
+    
+    # Applies options from a Hash. This method is primarily experimental
+    # (and proof of concept) at this time.
+    def apply_options(options)      
+      if options.kind_of? Hash
+        filters = options[:conditions]
+        if filters
+          if filters[:txn_date]
+            txn_date_filter = q.ORTxnQuery.TxnFilter.ORDateRangeFilter.TxnDateRangeFilter.ORTxnDateRangeFilter.TxnDateFilter
+            txn_date_filter.FromTxnDate.SetValue( filters[:txn_date][0] ) if filters[:txn_date][0]
+            txn_date_filter.ToTxnDate.SetValue( filters[:txn_date][1] ) if filters[:txn_date][1]
+            filters.delete(:txn_date)
+          end
+          
+          if filters[:ref_number]
+            ref_num_filter = q.send("OR#{self.qb_name}Query").send("#{self.qb_name}Filter").
+                             ORRefNumberFilter.RefNumberRangeFilter
+            ref_num_filter.FromRefNumber.SetValue( filters[:ref_number][0] ) if filters[:ref_number][0]
+            ref_num_filter.ToRefNumber.SetValue( filters[:ref_number][1] ) if filters[:ref_number][1]
+            filters.delete(:ref_number)
+          end
+            
+          filters.each do |filter, value|
+            q.send("OR#{self.qb_name}Query").
+              send("#{self.qb_name}Filter").
+              send("#{filter}=", QBFC_CONST::PsNotPaidOnly)
+          end
+            
+          options.delete(:conditions)
+        end
+          
+        add_owner_ids(options.delete(:owner_id))
+
+        options.each do |key, value|
+          q.send(key.to_s.camelize).SetValue(value)
+        end
+      end
+    end
+    
+    
+    # Add one or more OwnerIDs to the Request. Used in retrieving
+    # custom fields (aka private data extensions).
+    # Argument should be a single ID or an Array of IDs.
+    def add_owner_ids(ids)
+      return if ids.nil?
+      
+      ids = [ids] unless ids.respond_to?(:each)
+      ids.each do | id |
+        @request.OwnerIDList.Add(id)
+      end
+    end
+    
+    # Send missing methods to @ole_object (OLEWrapper)
+    def method_missing(symbol, *params) #:nodoc:
+      @request.qbfc_method_missing(@sess, symbol, *params)
+    end
+    
+    # Return Array of ole_methods for request WIN32OLE object.
+    # This is mostly useful for debugging.
+    def ole_methods
+      @request.ole_methods
+    end
+
+    # Return XML for the request WIN32OLE object.
+    # This is mostly useful for debugging.
+    def to_xml
+      @request_set.ToXMLString
+    end
+
+    # Submit Request and return full response as XML.
+    # This is mostly useful for debugging.    
+    def response_xml
+      @sess.DoRequests(@request_set).ToXMLString
+    end
+    
+    # Return actual WIN32OLE object
+    def ole_object
+      @request.ole_object
+    end
+  end
+end

data/lib/qbfc/session.rb

@@ -0,0 +1,136 @@
+module QBFC
+  class QuickbooksClosedError < RuntimeError #:nodoc:
+  end
+  class SetValueMissing < RuntimeError#:nodoc:
+  end
+  class QBXMLVersionError < RuntimeError#:nodoc:
+  end
+  class UnknownRequestError < RuntimeError#:nodoc:
+  end
+  class BaseClassNewError < RuntimeError#:nodoc:
+  end
+  class NotSavableError < RuntimeError#:nodoc:
+  end
+
+  # Encapsulates a QBFC session.
+  # 
+  #   QBFC::Session.open(:app_name => 'Test Application') do |qb|
+  #     qb.customers.find(:all).each do |customer|
+  #       puts customer.full_name
+  #     end
+  #   end
+  # 
+  #   qb = QBFC::Session.new(:app_name => 'Test Application')
+  #   qb.customers.find(:all).each do |customer|
+  #     puts customer.full_name
+  #   end
+  #   qb.close
+  # 
+  # A QBFC::Session abstracts the ole_methods so that more conventional Ruby method names are used,
+  # e.g. <tt>full_name</tt> instead of <tt>FullName.GetValue()</tt>.
+  # 
+  # This also allows a shortcut for setting up Quickbooks objects:
+  # 
+  # - session.customers.find(:all) instead of QBFC::Customer.find(session, :all)
+  # - session.customer('CustomerFullName') instead of QBFC::Customer.find(session, 'CustomerFullName')
+  # - session.customer instead of QBFC::Customer.find(session, :first)
+  class Session
+    class << self
+      
+      # Open a QBFC session. Takes options as a hash, and an optional block. Options are:
+      # 
+      # - +app_name+: Name that the application sends to Quickbooks (used for allowing/denying access)
+      #   (defaults to 'Ruby QBFC Application'
+      # - +app_id+: Per the Quickbooks SDK (QBFC Language Reference):
+      #   'Normally not assigned. Use an empty string for appID.' An empty string is passed by default.
+      # - +conn_type+: QBFC_CONST::CtUnknown, CtLocalQBD, CtRemoteQBD, CtLocalQBDLaunchUI, or CtRemoteQBOE.
+      #   Default is QBFC_CONST::CtLocalQBD (1)
+      # - +filename+: The full path to the Quickbooks file; leave blank to connect to the currently
+      #   open company file. Default is an empty string (Quickbooks should be running).
+      # - +open_mode+: The desired access mode. It can be one of three values:
+      #     - QBFC_CONST::OmSingleUser (specifies single-user mode)
+      #     - QBFC_CONST::OmMultiUser (specifies multi-user mode)
+      #     - QBFC_CONST::OmDontCare (accept whatever mode is currently in effect, or single-user mode if no other mode is in effect)
+      #   Default is QBFC_CONST::OmDontCare
+      #   
+      # If given a block, it yields the Session object and closes the Session and Connection
+      # when the block closes.
+      # 
+      # Otherwise, it returns the new Session object.
+  
+      def open(*options, &block)
+        qb = new(*options)
+        if block_given?
+          begin
+            yield qb
+          ensure
+            qb.close
+          end
+        else
+          qb
+        end
+      end
+      
+    end
+    
+    # See Session.open for initialization options.
+    def initialize(options = {})
+      ole_object = WIN32OLE.new("QBFC6.QBSessionManager")
+  
+      ole_object.OpenConnection2(options[:app_id].to_s,
+                                  (options[:app_name] || "Ruby QBFC Application"),
+                                  (options[:conn_type] || QBFC_CONST::CtLocalQBD))
+  
+      begin
+        ole_object.BeginSession(options[:filename].to_s,
+                                 (options[:open_mode] || QBFC_CONST::OmDontCare))
+      rescue WIN32OLERuntimeError
+        ole_object.CloseConnection
+        ole_object = nil
+        raise QBFC::QuickbooksClosedError, "BeginSession failed: Quickbooks must be open or a valid filename specified."
+      end
+      
+      @ole_object = QBFC::OLEWrapper.new(ole_object)
+    end
+    
+    # Close the session with Quickbooks. If this is ommitted, Quickbooks will not close.
+    # Using a block with Session.open ensures the session is closed.
+    def close
+      @ole_object.EndSession
+      @ole_object.CloseConnection
+      @ole_object = nil
+    end
+    
+    # The classes method allows using <tt>session.classes.find</tt> instead of
+    # <tt>session.q_b_classes.find</tt>, for finds on QBClass.
+    def classes
+      QBFC::QBCollection.new(self, :QBClass)
+    end
+    
+    # Responsible for the conversion of ole_method name to more convential Ruby method names.
+    # This specifies the methods for setting up an Entity, such as a Customer, directly, which is
+    # not included in OLEWrapper (setting up entities that are children of another entity is).
+    # Send other missing methods on to OLE Wrapper
+    def method_missing(symbol, *params) #:nodoc:
+      if (('a'..'z') === symbol.to_s[0].chr && symbol.to_s[-1].chr != '=')
+        camelized_method = symbol.to_s.camelize.to_sym
+        single_camelized_method = symbol.to_s.singularize.camelize.to_sym
+        if QBFC.const_defined?(camelized_method)
+          if params[0]
+            return QBFC::const_get(camelized_method).find_by_unique_id(self, params[0])
+          else
+            return QBFC::const_get(camelized_method).find(self, :first)
+          end
+        elsif QBFC.const_defined?(single_camelized_method)
+          return  QBFC::QBCollection.new(self, single_camelized_method)
+        end
+      end
+      
+      # Don't want to pass an OLEWrapper to a WIN32OLE method.
+      params = params.collect{ |p| p.respond_to?(:ole_object) ? p.ole_object : p }
+      
+      @ole_object.qbfc_method_missing(self, symbol, *params)
+    end
+    
+  end
+end

data/lib/qbfc/terms.rb

@@ -0,0 +1,10 @@
+module QBFC
+  class Terms < List
+    is_base_class
+  end
+end
+
+# Require subclass files
+Dir[File.dirname(__FILE__) + '/terms/*.rb'].each do |file|
+  require file
+end

data/lib/qbfc/terms/generated.rb

@@ -0,0 +1,10 @@
+module QBFC
+  
+  # Generated Terms Types (Inherit from List)
+  TERMS_TYPES = %w{DateDrivenTerms StandardTerms}
+  
+  # Generate Terms subclasses
+  # NB: All Terms are Modifiable
+  generate(TERMS_TYPES, Terms)
+  
+end

data/lib/qbfc/transaction.rb

@@ -0,0 +1,83 @@
+require File.dirname(__FILE__) + '/voidable'
+
+module QBFC
+  class Transaction < Element
+    is_base_class
+    ID_NAME = "TxnID"
+    
+    class << self
+      
+      # Find by Reference Number of the Transaction record.
+      # +options+ are the same as those for in +find+.
+      def find_by_ref(sess, ref, options = {})
+        q = create_query(sess)
+        q.query.RefNumberList.Add(ref)
+        find(sess, :first, q, options)
+      end
+      
+      # Find by TxnID of List record.
+      # +options+ are the same as those for in +find+.      
+      def find_by_id(sess, id, options = {})
+        q = create_query(sess)
+        q.query.TxnIDList.Add(id)
+        find(sess, :first, q, options)
+      end
+      
+      # Find by either ref or id. Tries id first, then ref.
+      def find_by_ref_or_id(*args)
+        find_by_id(*args) || find_by_ref(*args)
+      end
+      
+      alias_method :find_by_unique_id, :find_by_ref_or_id
+      
+    end
+    
+    # Alias of TxnID for this record.
+    def id
+      @ole.txn_id
+    end
+    
+    # Delete this Transaction
+    def delete
+      req = QBFC::Request.new(@sess, "TxnDel")
+      req.txn_del_type = QBFC_CONST::const_get("Tdt#{qb_name}")
+      req.txn_id = id
+      req.submit
+      return true
+    end
+    
+    # Change cleared status of transaction
+    # status can be one of:
+    # - QBFC::CsCleared (or true)
+    # - QBFC::CsNotCleared (or false)
+    # - QBFC::CsPending
+    def cleared_status=(status)
+      req = QBFC::Request.new(@sess, "ClearedStatusMod")
+      req.txn_id = id
+      status = QBFC_CONST::CsCleared if status === true
+      status = QBFC_CONST::CsNotCleared if status === false
+      req.cleared_status = status
+      req.submit
+      return status
+    end
+    
+    # Display the Transaction add (for new records) or edit dialog box
+    def display
+      if new_record?
+        req = QBFC::Request.new(@sess, "TxnDisplayAdd")
+        req.txn_display_add_type = QBFC_CONST::const_get("Tdat#{qb_name}")
+      else
+        req = QBFC::Request.new(@sess, "TxnDisplayMod")
+        req.txn_display_mod_type = QBFC_CONST::const_get("Tdmt#{qb_name}")
+        req.txn_id = id
+      end
+      req.submit
+      return true
+    end
+  end
+end
+
+# Require subclass files
+Dir[File.dirname(__FILE__) + '/transactions/*.rb'].each do |file|
+  require file
+end