Class QBFC::Session
In: lib/qbfc/session.rb
Parent: Object

Encapsulates a QBFC session. => 'Test Application') do |qb|
    qb.customers.find(:all).each do |customer|
      puts customer.full_name

  qb = => 'Test Application')
  qb.customers.find(:all).each do |customer|
    puts customer.full_name

A QBFC::Session abstracts the ole_methods so that more conventional Ruby method names are used, e.g. full_name instead of FullName.GetValue().

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)


classes   close   new   open   report  

Public Class methods

See for initialization options.


    # File lib/qbfc/session.rb, line 77
77:     def initialize(options = {})
78:       ole_object ="QBFC6.QBSessionManager")
80:       ole_object.OpenConnection2(options[:app_id].to_s,
81:                                   (options[:app_name] || "Ruby QBFC Application"),
82:                                   (options[:conn_type] || QBFC_CONST::CtLocalQBD))
84:       begin
85:         ole_object.BeginSession(options[:filename].to_s,
86:                                  (options[:open_mode] || QBFC_CONST::OmDontCare))
87:       rescue WIN32OLERuntimeError
88:         ole_object.CloseConnection
89:         ole_object = nil
90:         raise(QBFC::QuickbooksClosedError,
91:             "BeginSession failed: Quickbooks must be open or a valid filename specified.\n\n#{$!}")
92:       end
94:       @ole_object =
95:     end

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.


    # File lib/qbfc/session.rb, line 61
61:       def open(*options, &block)
62:         qb = new(*options)
63:         if block_given?
64:           begin
65:             yield qb
66:           ensure
67:             qb.close
68:           end
69:         else
70:           qb
71:         end
72:       end

Public Instance methods

The classes method allows using session.classes.find instead of session.q_b_classes.find, for finds on QBClass.


     # File lib/qbfc/session.rb, line 113
113:     def classes
114:, :QBClass)
115:     end

Close the session with Quickbooks. If this is ommitted, Quickbooks will not close. Using a block with ensures the session is closed.


     # File lib/qbfc/session.rb, line 99
 99:     def close
100:       @ole_object.EndSession
101:       @ole_object.CloseConnection
102:       @ole_object = nil
103:     end

Generate a report with the given name and args. (See QBFC::Report.get for details).


     # File lib/qbfc/session.rb, line 107
107:     def report(name, *args)
108:       Report.get(self, name, *args)
109:     end