Redistributing SDK components with your application

These are optional because you need only to distribute the component that your application actually uses, for example, if you are using only QBFC you redistribute the QBFC component, not any of the others.

Any of the installers or merge modules within the QB SDK install subdirectories toolsInstallers or toolsMergeModules can be redistributed. Currently these include QBFC, RDS, the QBO connector, and the web connector.

Note

Note

You can never redistribute the request processor DLL (qbxmlrp.dll or qbxmlrp2.dll). This violates the license agreement and can lead to undesirable user experiences.

Using the installers and merge modules

If you are using the QBFC API, the Remote Data Sharing (RDS) feature, the QBO connector or the web connector in your application, there are only two supported ways in which you can distribute our redistributable components:

Note

Note

NOTE: It is a violation of your qbXML license agreement to redistribute QBFC, RDS, the QBO connector, or the web connector without using either our stand-alone installers or our merge modules.

Do not use automatic installation programs and packaging wizards, such as the wizard in Microsoft® Visual Studio®. These will not install properly (even if you are using .NET), for the following reasons:

  1. You can use the stand-alone compressed-image installers that we provide.
  2. You can use the merge modules that we provide.
    • Automatic solutions will redistribute the qbxmlrp.dll file. Redistributing this file is against your license agreement, and could also cause significant problems for your end users.
    • Automatic solutions will redistribute the QBFC DLL file or files, but not the Xerces files that must go with them.

Note

Note

The QBFC library requires the Microsoft system DLL ShFolder.dll to be installed on the system. Newer Microsoft operating systems (Windows ME, Windows XP, etc.) have this DLL pre-installed. This DLL is installed if needed by QuickBooks and by the QBFC stand-alone installer using the SHFolder.exe redistributable installer from Microsoft. If you plan to use the QBFC merge module in your installer and you want your application to work with RDS (where QuickBooks may not be installed on the machine where your application is installed) then your installer must include and execute the SHFolder.exe installer from Microsoft. Technical issues prevent us from including this action in the QBFC merge module itself.

Using the stand-alone installers

If your install process does not support merge modules, you will need to use the stand-alone installers provided with the SDK. These installers will automatically perform a proper installation.

To install the QBFC Library on your end-users’ machines:

QBFC1, QBFC2, QBFC2CA, QBFC2_1, QBFC3, QBFC4, and QBFC5 can be installed side-by-side on the same computer. The stand-alone installer for QBFC4 will install QBFC4 and QBXMLRP2.

Using the merge modules

If your install process supports Microsoft merge modules, you can use the merge modules that are provided.

What Is a merge module?

The Microsoft Installer (MSI) service is built into Windows 2000 and XP. MSI solves a number of installation problems, such as getting clean uninstalls and protecting system components, and includes redistributable install engines that support Win98, WinNT, and Win ME. To get a “Designed for Windows” logo, your application must be installed using MSI.

“Merge modules” are a key part of MSI. They encode the logic and files needed to correctly redistribute shared components, which aren’t removed from a system until all of the applications that installed them are removed.

Any installation that is built for an MSI-engine installer can use merge modules. Many proprietary install tools that are not strictly based on MSI (for example, newer versions of InstallShield Professional) can also take advantage of merge modules.

How Do I Use a Merge Module from the SDK?

The SDK merge modules are located in the /tools/MergeModules folder.

Here’s how to use them:

  1. Make sure you have the Microsoft VC (VC_CRT.msm) and VC++ (VC_STL.msm) runtime library merge modules, which are required because the SDK merge modules install components that depend on the Visual C and C++ version 7 runtime libraries. These Microsoft merge modules are included with most MSI-based install builders, or you can get them directly from Microsoft. When the VC_CRT.msm and VC_STL.msm modules are added to the installer, the install author is responsible for configuring them to set their target directory to the windows system directory.
  2. Set your installation development tool to include the SDK MergeModules directory in the MergeModule search path.
  3. Each MSI “feature” refers to components and/or merge modules. For any feature that installs components of your application that depend on the SDK capabilities provided by a merge module, specify that particular merge module as part of that feature. If a merge module is dependent on some other module, the other module will be added to your installer automatically. (For example, the various versions of the QBFC merge modules depend on various versions of Xerces, which are packaged in separate merge modules: the correct one is automatically added to the installation.)
  4. Build your installation as usual. All the logic from the included merge modules will be merged into your install.
What Installation Logic Is Built Into the Provided Merge Modules?

The QBFC merge modules provide QBFC DLL files and COM registration information for QBFC. The QBFC merge modules depend on the Xerces XML parser module and on the QBXMLRP2 merge module—in other words, installing QBFC installs the Xerces files and QBXMLRP2.