You are on page 1of 134

QuickBooks SDK

Developers Guide

for the QBFC Library

QBFC4

SDK version 4.0, released November 2004. (c) 2004 Intuit Inc. All rights reserved. QuickBooks and Intuit are registered trademarks of Intuit Inc. All other trademarks are the property of their respective owners and should be treated as such. Acknowledgement: This product includes software developed by the Apache Software Foundation (<http://www.apache.org>) (c) 1999-2004 The Apache Software Foundation. All rights reserved. Intuit Inc. P.O. Box 7850 Mountain View, CA 94039-7850 For more information about the QuickBooks SDK and the SDK documentation, visit http://developer.intuit.com/QuickBooksSDK/.

CONTENTS
About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .ix
Whats New in QBFC4 . . . . . . . . . . Who Should Read This Guide . . . . . Before You Begin . . . . . . . . . . . . . Sample Code . . . . . . . . . . . . . What if I Dont Want to Use QBFC? . Whats in This Guide? . . . . . . . . . . Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix . x . x . xi .xii .xii .xii

Chapter 1: Introduction
Versions of QBFC . . . . . . . . . . . . . . . . . . . Migrating to QBFC4. . . . . . . . . . . . . . . . . . About QuickBooks Online Edition . . . . . . . . About Canadian Editions of QuickBooks. . . . Starting from the Beginning. . . . . . . . . . . . Installing QBFC . . . . . . . . . . . . . . . . . . Sample Program: Adding a Customer . . The Process of Interacting with QuickBooks . qbXML Data Types in QBFC . . . . . . . . . . . . Categories of Objects in QBFC . . . . . . . . . . Using IntelliSense . . . . . . . . . . . . . . . . Using the Visual Studio 2003 Plug-in . . . Using the Onscreen Reference . . . . . . . Registering and Signing Your Application . . . Distributing Your Application . . . . . . . . . . . Using the Stand-Alone Installers . . . . . . Using the Merge Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 . 2 . 3 . 4 . 5 . 5 . 5 . 7 14 14 16 17 17 18 18 19 19

Chapter 2: Communicating with QuickBooks


Enabling Users to Authorize Your Application . . . . . . . . . . . . . . . . . . . . When is the Authorization Dialog Displayed?. . . . . . . . . . . . . . . . . . The Default Authorization Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . Using QBAuthPreferences to Obtain Proper Application Authorization . Setting Authorization Preferences Within QuickBooks. . . . . . . . . . . . More Information about Login Modes . . . . . . . . . . . . . . . . . . . . . . . More Information on Accessing Personal Data . . . . . . . . . . . . . . . . . More Information on Single-User vs. Multi-User Mode . . . . . . . . . . . Using the Session Manager to Communicate with QuickBooks . . . . . . . . Functions of QBSessionManager and QBOESessionManager . . . . . . . . . . CreateMsgSetRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DoRequests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 21 22 23 24 25 27 27 29 33 33 34

Contents iii
(c) 2004 Intuit Inc. All rights reserved.

GetVersion. . . . . . . . . . . . . . . . . . . . . ToMsgSetResponse . . . . . . . . . . . . . . . DoRequestsFromXMLString . . . . . . . . . ToMsgSetRequest . . . . . . . . . . . . . . . . IsErrorRecoveryInfo . . . . . . . . . . . . . . ClearErrorRecovery. . . . . . . . . . . . . . . EnableErrorRecovery. . . . . . . . . . . . . . ErrorRecoveryID. . . . . . . . . . . . . . . . . SaveAllMsgSetRequestInfo . . . . . . . . . GetErrorRecoveryStatus . . . . . . . . . . . GetSavedMsgSetRequest. . . . . . . . . . . Functions of QBSessionManager . . . . . . . . OpenConnection2 . . . . . . . . . . . . . . . . CloseConnection. . . . . . . . . . . . . . . . . BeginSession . . . . . . . . . . . . . . . . . . . EndSession . . . . . . . . . . . . . . . . . . . . GetCurrentCompanyFileName . . . . . . . QBXMLVersionsForSession . . . . . . . . . . QBXMLVersionsForSubscription . . . . . . CreateSubscriptionMsgSetRequest . . . . DoSubscriptionRequestsFromXMLString ToSubscriptionMsgSetResponse . . . . . . DoSubscriptionRequests . . . . . . . . . . . ToEventsMsgSet . . . . . . . . . . . . . . . . . CommunicateOutOfProcess . . . . . . . . . ConnectionType . . . . . . . . . . . . . . . . . QBAuthPreferences. . . . . . . . . . . . . . . Functions of QBAuthPreferences . . . . . . . . QBAuthPreferences. . . . . . . . . . . . . . . GetIsReadOnly . . . . . . . . . . . . . . . . . . PutIsReadOnly . . . . . . . . . . . . . . . . . . GetUnattendedModePref . . . . . . . . . . . PutUnattendedModePref . . . . . . . . . . . GetPersonalDataPref . . . . . . . . . . . . . . PutPersonalDataPref . . . . . . . . . . . . . . WasAuthPreferencesObeyed . . . . . . . . Functions of QBOESessionManager . . . . . . ApplicationLogin . . . . . . . . . . . . . . . . . ConnectionTicket . . . . . . . . . . . . . . . . InstallationID. . . . . . . . . . . . . . . . . . . Language . . . . . . . . . . . . . . . . . . . . . AppID . . . . . . . . . . . . . . . . . . . . . . . . AppVer . . . . . . . . . . . . . . . . . . . . . . . SessionTicket. . . . . . . . . . . . . . . . . . . AuthID . . . . . . . . . . . . . . . . . . . . . . . Automated Error Recovery . . . . . . . . . . . . Event Notification . . . . . . . . . . . . . . . . . . Subscription . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. 34 . 35 . 36 . 36 . 36 . 37 . 37 . 37 . 37 . 38 . 38 . 38 . 38 . 39 . 39 . 41 . 42 . 42 . 43 . 43 . 44 . 44 . 45 . 45 . 46 . 46 . 47 . 47 . 48 . 48 . 48 . 49 . 49 . 49 . 50 . 50 . 51 . 51 . 51 . 51 . 52 . 52 . 52 . 52 . 52 . 53 . 54 . 54

iv

Contents
(c) 2004 Intuit Inc. All rights reserved.

Callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Event Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Chapter 3: High-Level Request Objects


IMsgSetRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ClearRequests . . . . . . . . . . . . . . . . . . . . . . . . . . RequestList. . . . . . . . . . . . . . . . . . . . . . . . . . . . ToXMLString . . . . . . . . . . . . . . . . . . . . . . . . . . . Verify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to Append Requests to the Request Message . IRequestList. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Count. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GetAt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RequestID . . . . . . . . . . . . . . . . . . . . . . . . . . . . Detail. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IAttributesRqSet. . . . . . . . . . . . . . . . . . . . . . . . . . . OnError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OldMessageSetID . . . . . . . . . . . . . . . . . . . . . . . NewMessageSetID . . . . . . . . . . . . . . . . . . . . . . . ResponseData . . . . . . . . . . . . . . . . . . . . . . . . . . ISubscriptionMsgSetRequest . . . . . . . . . . . . . . . . . . ClearRequests . . . . . . . . . . . . . . . . . . . . . . . . . . ToXMLString . . . . . . . . . . . . . . . . . . . . . . . . . . . Verify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AppendUIEventSubscriptionQueryRq . . . . . . . . . . AppendUIExtensionSubscriptionQueryRq . . . . . . . AppendDataEventSubscriptionQueryRq . . . . . . . . AppendUIExtensionSubscriptionAddRq . . . . . . . . . AppendUIEventSubscriptionAddRq. . . . . . . . . . . . AppendDataEventSubscriptionAddRq . . . . . . . . . . AppendSubscriptionDelRq. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 59 60 60 60 60 61 62 62 62 63 63 63 63 63 63 64 64 65 65 65 65 65 66 66 66 66 66 66 66

Chapter 4: High-Level Response Objects


IMsgSetResponse . ResponseList. . Attributes . . . . ToXMLString . . IResponseList . . . Count. . . . . . . GetAt . . . . . . . IResponse . . . . . . retCount. . . . . StatusCode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 67 67 68 68 68 68 69 69 69 v

Contents
(c) 2004 Intuit Inc. All rights reserved.

StatusSeverity . . . . . . . . . StatusMessage. . . . . . . . . Detail . . . . . . . . . . . . . . . Type . . . . . . . . . . . . . . . . IAttributesRsSet . . . . . . . . . . NewMessageSetID . . . . . . MessageSetStatusCode . . . ISubscriptionMsgSetResponse. ResponseList . . . . . . . . . . ToXMLString . . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

69 70 70 71 71 71 72 72 72 72

Chapter 5: Message Data Objects


Limiting Data Returned in Responses . . . IQBBase . . . . . . . . . . . . . . . . . . . . . . . Type . . . . . . . . . . . . . . . . . . . . . . . Add Objects . . . . . . . . . . . . . . . . . . . . Mod Objects . . . . . . . . . . . . . . . . . . . . Del Objects. . . . . . . . . . . . . . . . . . . . . IListDel . . . . . . . . . . . . . . . . . . . . . ITxnDel . . . . . . . . . . . . . . . . . . . . . Void Objects . . . . . . . . . . . . . . . . . . . . ITxnVoid . . . . . . . . . . . . . . . . . . . . Ret Objects. . . . . . . . . . . . . . . . . . . . . Query Objects . . . . . . . . . . . . . . . . . . . Basic Aggregate Objects. . . . . . . . . . . . Group Objects. . . . . . . . . . . . . . . . . . . ORGroup Objects. . . . . . . . . . . . . . . . . List Objects . . . . . . . . . . . . . . . . . . . . Examples of Data Objects. . . . . . . . . . . Subscription and Event Callback Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 . 74 . 74 . 74 . 75 . 76 . 77 . 77 . 77 . 77 . 78 . 79 . 80 . 81 . 82 . 84 . 86 . 87

Chapter 6: Data Type Objects


IBasicPropertyType . . . . . . . . . . . . . Enum Data Types . . . . . . . . . . . . . . Example: IQBENActiveStatusType IQBAmountType . . . . . . . . . . . . . . . IQBBoolType . . . . . . . . . . . . . . . . . . IQBDateType. . . . . . . . . . . . . . . . . . IQBDateTimeType . . . . . . . . . . . . . . IQBFloatType . . . . . . . . . . . . . . . . . IQBIDType . . . . . . . . . . . . . . . . . . . IQBIntType . . . . . . . . . . . . . . . . . . . IQBPercentType. . . . . . . . . . . . . . . . IQBPriceType . . . . . . . . . . . . . . . . . IQBQuanType . . . . . . . . . . . . . . . . . IQBStringType. . . . . . . . . . . . . . . . . vi
Contents
(c) 2004 Intuit Inc. All rights reserved.

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. 89 . 90 . 90 . 91 . 93 . 93 . 94 . 95 . 96 . 97 . 98 . 99 100 101

IQBTimeIntervalType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102 IQBGuidType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102

Appendix A: Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Appendix B: Integrating with Canadian Editions of QuickBooks . . . . 107
QBFC Features Unique to Canada . . . . Tax Differences . . . . . . . . . . . . . . Employee and Address Information About Units of Measure . . . . . . . . . . . About UI Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107 .107 .108 .110 .111

Index of QBFC Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 Index of Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Contents vii
(c) 2004 Intuit Inc. All rights reserved.

viii Contents
(c) 2004 Intuit Inc. All rights reserved.

ABOUT THIS GUIDE

This Developers Guide describes the QuickBooks Foundation Class (QBFC) Library, which can be used to communicate with U.S. and Canadian editions of QuickBooks and with QuickBooks Online Edition.

Whats New in QBFC4


QBFC4 supports all the new features of version 4.0 of qbXML, plus some new features of its own: Additional functionality for QBFC event notification and UI integration, such as > > > > > The ability to filter out for an application those events generated by the application itself The ability to obtain QuickBooks context information (which QuickBooks form is currently open) when the applications custom menu is clicked. The ability to prefill data such as customer information in QuickBooks transaction creation forms. The ability to launch the QuickBooks UI from an application running in background (auto login) mode. QBFC-specific aspects of event notification are described in Event Notification on page 54. (Event notification and UI integration are described in more detail in the Concepts Manual.)

New session manager functionality including support for user authorization preferences and support for the new OpenConnection2 method. See Functions of QBSessionManager and QBOESessionManager (page 33). The new OpenConnection2 method can be used to connect to both QuickBooks and QBOE editions, as well as through RDS. Support for out-of-process communication via a method call that is invoked prior to opening a connection. New metaData attribute that returns a count only from a query. New IncludeRetElementList element in requests that lets you specify which standalone elements or aggregates are to be included in the response. If Visual Studio .Net 2003 is installed on your system, the SDK automatically installs a help plug-in that provides SDK documentation, OSR, and F1 keyword help from within the Visual Studio IDE. It also provides sample code.

Whats New in QBFC4


(c) 2004 Intuit Inc. All rights reserved.

ix

Who Should Read This Guide


This guide is written for developers who are using the QBFC API to create applications that integrate with QuickBooks. It explains how to use the objects in QBFC and provides a detailed description of them, making the following assumptions: You have access to the version 4.0 QuickBooks SDK documentation set. Understanding some aspects of QBFC requires knowledge of qbXML, which is not covered here. While you read this document you might want to refer to other parts of the documentation set, which is described in the next section, Before You Begin. You are comfortable calling COM objects and can understand sample code in Microsoft Visual Basic (VB). Because most COM users have experience with VB or can interpret it fairly easily, most of the sample code in this guide is written in VB.

Before You Begin


This guide assumes youre already familiar with the introductory material and key concepts contained in the QuickBooks SDK Technical Overview and Concepts Manual. The Onscreen Reference is extremely important when you are writing your code because it contains the syntax for each request and response message type, descriptions of each element, descriptions of status codes and HRESULT values, VB and VB.Net samples for each request and response. For more information, see Using the Onscreen Reference (page 17). Figure 1 shows the complete SDK documentation set and the other documents youll consult as you develop your application.

About This Guide


(c) 2004 Intuit Inc. All rights reserved.

You are here

Developers Guide for QuickBooks (U.S. and Canadian Editions) Onscreen Reference for QuickBooks (U.S.) QuickBooks (Canadian) QuickBooks Online Edition, QBFC (U.S.) QBFC (Canadian)

Technical Overview

Concepts Manual

Developers Guide for QBFC

Developers Guide for QuickBooks Online Edition

(Strongly Recommended for Any Programming in the SDK)

2
What is in a QuickBooks message? How do I use the information contained in the messages?

What is the QuickBooks SDK?

How does my application What is the exact syntax for a given message? communicate with QuickBooks?

Figure 1

Documentation Roadmap

You can find these manuals on the Intuit Developer Network (IDN) Web site: http://developer.intuit.com/QuickBooksSDK/Resources/

Sample Code
The SDK includes a number of sample programs that use the QBFC library: To find samples written in various programming languages, see the \samples\readme.html file in the folder where you installed the SDK, or select Samples in the QuickBooks SDK area of your Start menu. In the QBFC section of the Onscreen Reference, you can view a Visual Basic and a VB.Net sample program for each request in the SDK. For direct access to the VB6 or VB.Net project files associated with these samples, see the folders \OSR\OnscreenRef\SampleCode\VB6 or OSR\OnscreenRef\SampleCode\VB.NET in the folder where you installed the SDK.

Before You Begin


(c) 2004 Intuit Inc. All rights reserved.

xi

What if I Dont Want to Use QBFC?


An alternative to using the QBFC Library is to use the QBXML Request Processor API, plus an API for building and parsing XML. The QBXMLRP and QBXMLRP2 API requires you to construct qbXML messages, interpret qbXML responses from QuickBooks, and use a small COM library to communicate with QuickBooks. For more information, see the Technical Overview.

Whats in This Guide?


This Developers Guide contains the following chapters: Chapter 1, Introduction, presents a conceptual overview of the process of interacting with QuickBooks via QBFC, and introduces the QBFC data types and objects. Chapter 2, Communicating with QuickBooks, describes the objects in the QBFC Library that are responsible for all communication with QuickBooks. The chapter also describes automated error recovery and QBFC-specific aspects of event notification. Chapter 3, High-Level Request Objects, describes IMsgSetRequest, IAttributesRqSet, and ISubscriptionMsgSetRequest, the objects in the QBFC Library that pertain to request information (excluding the actual message content). Chapter 4, High-Level Response Objects, describes IMsgSetResponse, IResponseList, IResponse, IAttributesRsSet, and ISubscriptionMsgSetResponse, the objects in the QBFC Library that pertain to response information (excluding the actual message content). Chapter 5, Message Data Objects, describes IQBBase (from which all message data objects derive), the top-level message data objects, and the types of information that these top-level objects can contain. Chapter 5 also describes subscription and callback objects. Chapter 6, Data Type Objects, describes data type objects, which are the objects in the QBFC Library that correspond to qbXML data types, and IBasicPropertyType, the interface from which all data type objects derive. Appendix A, Error Codes, lists the QBFC error codes and gives a brief description of each one. Appendix B, Integrating with Canadian Editions of QuickBooks, highlights the differences between the U.S. and Canadian editions of QuickBooks. Two indexes are included: an alphabetical list of QBFC functions (page 113) and an index of topics (page 115).

Document Conventions
Sample programs that are referenced by a name, such as ItemQuery or Macro, are in the samples\qbdt\vb\qbfc or samples\qbdt\cpp\qbfc folders. (To download the samples and the rest of the SDK, visit http://developer.intuit.com/QuickBooksSDK/

xii About This Guide


(c) 2004 Intuit Inc. All rights reserved.

Downloads/.) Any reference to an unnamed sample program, on the other hand, corresponds to the sample program shown in Listing 1-1 in the next chapter. In this guide, QBFC refers to the most recent version of the QBFC Library, which is QBFC4.

Whats in This Guide? xiii


(c) 2004 Intuit Inc. All rights reserved.

xiv About This Guide


(c) 2004 Intuit Inc. All rights reserved.

CHAPTER 1 INTRODUCTION

1 1

The QuickBooks Foundation Class (QBFC) Library enables you to write applications that share data with QuickBooks without having to build and parse qbXML in your code. Using QBFC, you can manipulate COM objects rather than raw qbXML, yet still have access to all the functionality of qbXML. QBFC is implemented as a COM library because COM is a language-independent technology that is relatively well-known. The QBFC Library will work with programming languages that support COM. The QBFC Library: Employs standard COM concepts, such as data types (BSTR, long, DATE, etc.), error handling, and method signatures. Supplies data type objects that provide the ability to enforce the qbXML data types. Matches object and element names to the underlying qbXML specification. Maintains the request-response model and the events model inherent in qbXML. Identifies mandatory fields, mutually exclusive elements, and expected data types. Provides quick and easy access to its methods and properties through the use of IntelliSense from the Microsoft Visual Studio editors. Provides SDK help, documentation, and sample code from within the Visual Studio 2003 IDE. Lists and describes its objects and data types in the Onscreen Reference, an HTMLbased reference for the entire QuickBooks SDK.

Versions of QBFC
QBFC exists in several versions: QBFC4 is the latest version, released in November 2004. QBFC4 is supported by 2005 U.S. editions of QuickBooks, and by version 11.0 and later of QuickBooks Online Edition. Notice that 2005 versions of Canadian QuickBooks still supports the 3.0 and 2.0 qbXML specification: they do not support the 4.0 qbXML specification. QBFC3 is supported by 2004 U.S. and Canadian editions of QuickBooks, and by version 10.0 and later of QuickBooks Online Edition. QBFC3 supports the 1.0, 1.1, 2.0, 2.0 Canada, 2.1, and 3.0 Canada qbXML specifications. QBFC2_1 is supported by 2003 R7 and later U.S. editions of QuickBooks. It supports the 1.0, 1.1, 2.0, and 2.1 qbXML specifications. QBFC2 is supported by 2002 and 2003 U.S. editions of QuickBooks. It supports the 1.0, 1.1, and 2.0 qbXML specifications.

Versions of QBFC
(c) 2004 Intuit Inc. All rights reserved.

QBFC2CA is supported by 2003 Canadian editions of QuickBooks, and it supports the Canadian version of the 2.0 qbXML specification.
NOTE:

QBFC2_1 does not have a Canadian counterpart.

QBFC1 is supported by 2002 U.S. editions of QuickBooks. It supports the 1.0 and 1.1 qbXML specifications.

NOTE There is also a patch release of the QBFC library, QBFC3b, which fixed some parsing bugs for the Canadian versions.

Migrating to QBFC4
IMPORTANT If you are currently using QBFC and want or need to be able to use the new QBFC DLL (qbfc4.dll), you may need to make a few changes to your code and recompile even if you continue specifying the 3.0 version of the qbXML spec.

To migrate working code that uses earlier versions of QBFC: 1. Change code and projects that reference older QBFC versions to instead reference QBFC4Lib. 2. For US versions of QuickBooks except QuickBooks Online Edition (QBOE), if you use ChargeQuery, change occurrences of ORTxnQuery to ORChargeTxnQuery. (For Canadian versions, ORTxnQuery is still used; for QBOE there is no change because QBOE doesn't support ChargeQuery.)

3. For US versions of QuickBooks except QBOE, if you use InvoiceLineAdd/ Mod, CreditMemoLineAdd/Mod, SalesOrderLineAdd/Mod, or SalesReceiptLineAdd, change occurrences of ORRate to ORRatePriceLevel. 4. For QBOE, if you use InvoiceLineAdd, CreditMemoLineAdd, or SalesReceiptLineAdd, change ORRate to ORRatePriceLevel, even though the new PriceLevelRef in ORRatePriceLevel is not available in QBOE. (For Canadian versions, ORRate is still used, so no change is needed.)
5. Replace any QBXMLRPConnectionType enum values (unknown, localQBD, remoteQBD) with the ENConnectionType enum values (ctUnknown, ctLocalQBD, ctRemoteQBD, ctLocalQBDLaunchUI, ctRemoteQBOE 6. Recompile your code. If it compiles successfully, youre done. If you are migrating from QBFC3 to QBFC4, this is probably all you will have to do. You may need to make more changes, particularly if your application uses QBFC versions older than QBFC3. Accordingly, if your code doesnt compile successfully, even after making the changes listed above: 1. Review the differences between the QBFC specifications, then change your code until it compiles without problems. (For information about the differences between qbXML
2
Chapter 1: Introduction
(c) 2004 Intuit Inc. All rights reserved.

versions, see Chapter 3 of the Technical Overview. You can find the Technical Overview in the QuickBooks SDK area of your Start menu, or online at http:// developer.intuit.com/QuickBooksSDK/Resources/.) For example, change calls to CreateMsgSetRequest to include the country parameter, which is required beginning with QBFC3. For more information, see CreateMsgSetRequest on page 33. Also, change DataExtAdd request objects to use ORListTxnWithMacro instead of ORListTxn, which is required as of QBFC3. (See the Onscreen Reference for the exact syntax.) If you are migrating from older SDK versions, between QBFC1 and QBFC2, the FromModifiedDate and ToModifiedDate fields changed from IQBDateType to IQBDateTimeType. If your original code uses QBFC1 and sets either of these fields, you need to pass a second Boolean parameter, named asDateOnly, in the SetValue method: > > Set asDateOnly to true if you want the exact 1.x functionality, which is equivalent to formatting the field as IQBDateType, not IQBDateTimeType. Set asDateOnly to false if you want the 2.0, 2.1, or 3.0 functionality, which is equivalent to formatting the field as IQBDateTimeType.

2. Re-test your application.


NOTE For more information about specification versions, see Software Versions in Chapter 8 of the Concepts Manual, especially the section called Dealing with Unsupported Features.

About QuickBooks Online Edition


IMPORTANT At present, QBFC support for QuickBooks Online Edition is limited to desktop applications. To build a server application you will need to manage the HTTPS connection to QuickBooks Online Edition and the sign-on messages yourself. You can still use QBFC to generate and parse qbXML.

Beginning with QBFC4, a new QBSessionManager method named OpenConnection2 is provided that allows you to specify the connection type, for example whether you are connecting to ordinary QuickBooks at the desktop or connecting to QBOE. If you specify a QBOE connection, a new software component called the QBOE connector is used to handle communication transparently with QBOE. (This software component is provided with SDK 4.0 and is redistributable.) Using this new QBOE connection method simplifies the task of porting or creating new QBOE applications using QBFC. However, the QBOESessionManager is still supported and your application can use it to connect to QBOE.
About QuickBooks Online Edition
(c) 2004 Intuit Inc. All rights reserved.

For building requests and interpreting responses, your application can use almost the same code when integrating with QuickBooks Online Edition as when integrating with desktop versions of QuickBooks. (But keep in mind that each supports a slightly different set of requests and fields. The Onscreen Reference shows these differences.) You can find information about integrating with QuickBooks Online Edition in four places: 1. The Developers Guide for QuickBooks Online Edition focuses on QuickBooks Online Edition and specific aspects of developing an application that integrates with it, for example, using a connection ticket. In particular, see > > > > Chapter 1, Overview In Chapter 3, the first section, Registering a Desktop Application Chapter 4, Integrating a Desktop Application The Appendixes.

2. This manual, the Developers Guide for the QBFC Library, describes QBFC-specific aspects of developing an application for QuickBooks Online Edition. In particular, see > > > The Process of Interacting with QuickBooks (page 7), especially Integrating This Sample with QuickBooks Online Edition (page 8) Using the Session Manager to Communicate with QuickBooks (page 29) In Chapter 5, the examples in the Add Objects, Mod Objects, and Ret Objects sections.

3. The BillAdd sample written in VB (not the BillAdd sample written in C++) shows how to write code that can establish communication either with a desktop version of QuickBooks or with QuickBooks Online Edition, depending on a preference set by your applications user. This sample is in the \samples\qbdt\vb\qbfc\billadd folder. 4. In the Onscreen Reference for QBFC4, the Max (QBOE) column shows the maximum lengths of strings for QuickBooks Online Edition. Not in QBOE appears in the Implementation column for messages and fields that are not relevant or not supported in QuickBooks Online Edition.

About Canadian Editions of QuickBooks


You can find information about integrating with Canadian editions of QuickBooks in the following places: 1. This manual covers QBFC aspects of integrating with Canadian editions of QuickBooks. In particular, see Appendix B, Integrating with Canadian Editions of QuickBooks. 2. In the Onscreen Reference for QBFC4, the Max (desk) column shows the maximum lengths of strings for both U.S. and Canadian editions of QuickBooks. Not in QBCA appears in the Implementation column for messages and fields that are not relevant or not supported in Canadian editions of QuickBooks.

Chapter 1: Introduction
(c) 2004 Intuit Inc. All rights reserved.

Starting from the Beginning


This section gives instructions for installing QBFC in your development environment and provides the source code of a small program that you can try out.

Installing QBFC
The SDK installer will put the library for QBFC4 on your machine. Multiple versions of QBFC can be installed side-by-side on the same computer. When you redistribute QBFC components to your end-users machines, you must either use the stand-alone installer that we provide or the merge modules that we provide. For more details, see Distributing Your Application (page 18).

Sample Program: Adding a Customer


The code in Listing 1-1 is a complete program that shows how you can use QBFC to add a customer to desktop versions of QuickBooks. In order for the program to work, QuickBooks must be running a company file for which you have administrator privileges. (When you run the sample program, a QuickBooks dialog box will appear asking you to grant data sharing permission.) Also, the customer name must be unique. If a customer with the given name already exists, QuickBooks will return an error. The discussion of the sample program in The Process of Interacting with QuickBooks (page 7) describes how you would alter the code to make it work with QuickBooks Online Edition.

Starting from the Beginning


(c) 2004 Intuit Inc. All rights reserved.

______ Listing 1-1 Sample program: adding a customer Option Explicit Public Sub Main() On Error GoTo ErrHandler 'Step 1: Establish a communication channel with QuickBooks 'Create the session manager object, and initiate a conversation with QuickBooks Dim sessionManager As New QBFC4Lib.QBSessionManager sessionManager.OpenConnection2 " ", "QBFC Developers Guide", ctLocalQBD sessionManager.BeginSession "", omDontCare

'Step 2: Build a set of requests in this case, containing only one request 'Create the request set (the message set request object) Dim requestSet As QBFC4Lib.IMsgSetRequest 'Create a qbXML version 4.0 message Set requestSet = sessionManager.CreateMsgSetRequest("US",4, 0) 'Add a request to the request set. Dim customerAdd As QBFC4Lib.ICustomerAdd 'AppendCustomerAddRq is called only once here, even though two values are being set. Set customerAdd = requestSet.AppendCustomerAddRq customerAdd.Name.SetValue "Joe" customerAdd.CustomerTypeRef.FullName.SetValue "East Coast" 'Indicate that all requests should be processed, even if one has an error requestSet.Attributes.OnError = roeContinue

'Step 3: Send the request set to QuickBooks Dim responseSet As QBFC4Lib.IMsgSetResponse Set responseSet = sessionManager.DoRequests(requestSet)

'Step 4: Check response status and data Dim response As QBFC4Lib.IResponse 'The response list contains only one response, corresponding to our single request Set response = responseSet.ResponseList.GetAt(0)

Chapter 1: Introduction
(c) 2004 Intuit Inc. All rights reserved.

'Any status code other than 0 should be investigated further If (response.StatusCode <> 0) Then MsgBox "Status: Code = " & CStr(response.StatusCode) & _ ", Severity = " & response.StatusSeverity & _ ", Message = " & response.StatusMessage End If 'Under normal circumstances, the response will contain an ICustomerRet object, 'corresponding to the added customer Dim customerRet As QBFC4Lib.ICustomerRet Set customerRet = response.Detail 'In this case, the ListID and the State (if it exists) are the returned 'data we will retrieve If Not (customerRet Is Nothing) Then MsgBox "CustomerRet ListID = " & customerRet.ListID.GetValue End If 'Must check that the parent object exists before checking for the child object If Not (customerRet.BillAddress Is Nothing) Then If Not (customerRet.BillAddress.State Is Nothing) Then MsgBox "The customer is billed in " & customerRet.BillAddress.State.GetValue End If End If 'Step 5: Relinquish the communication channel with QuickBooks sessionManager.EndSession sessionManager.CloseConnection Exit Sub ErrHandler: MsgBox Err.Description, vbExclamation, "Error" End Sub

The Process of Interacting with QuickBooks


Your application must go through five basic steps to exchange data with QuickBooks: 1. Establish a communication channel with QuickBooks (page 8). 2. Build a request set (page 9). 3. Send the request set to QuickBooks (page 11). 4. Check response status and data (page 11). (Repeat steps 2 through 4 until data exchange is completed.) 5. Relinquish the communication channel with QuickBooks (page 13).

The Process of Interacting with QuickBooks


(c) 2004 Intuit Inc. All rights reserved.

This section presents an overview of the process listed above, while a detailed description of the QBFC objects and data types that implement the process can be found in the next section and in the chapters that follow. 1. Establish a communication channel with QuickBooks The QBSessionManager handles all communication with QuickBooks and creates the object used to make requests. So, before anything else can happen, you must create the QBSessionManager object. Notice that beginning with QBFC4, the QBSessionManager object is able to handle communication with both QuickBooks and QuickBooks Online Edition using the OpenConnection2 method, which is new in QBFC4. The QBOESessionManager object, formerly required for QBFC to QBOE communication, still continues to be supported for QuickBooks Online Edition, although using the QBSessionManager with the new OpenConnection2 method is simpler.
NOTE QBSessionManager and QBOESessionManager are the only objects in QBFC that you create explicitly. All other objects are retrieved from the objects containing them.

After you have created the QBSessionManager object, you will use it to inform the SDK of your applications ID, name, and type of connection through the OpenConnection2 method. Then, using the BeginSession method, you will be able to initiate a conversation between your application and a specific QuickBooks company file. Consider the beginning of the sample program shown in Listing 1-1:
Dim sessionManager As New QBFC4Lib.QBSessionManager sessionManager.OpenConnection , QBFC Developers Guide, ctLocalQBD sessionManager.BeginSession , omDontCare

First, notice that this application identifies itself with a blank ID and the name QBFC Developers Guide. The ctLocalQBD parameter indicates that the connection must be made to QuickBooks installed locally. Second, notice that the first parameter to BeginSession (company file name) is an empty string, which means the application must use the company file that is currently running in QuickBooks. If that company file has not already granted data sharing permission to this application, it will display a dialog box to prompt a user with administrator privileges to grant such access. If either OpenConnection2 or BeginSession fails for any reason, an error HRESULT will be returned. These two methods and their partners, CloseConnection and EndSession, are important but often misunderstood. Refer to Using the Session Manager to Communicate with QuickBooks (page 29) for more information about them.
Integrating This Sample with QuickBooks Online Edition

To integrate the sample program shown in Listing 1-1 with QuickBooks Online Edition, you would simply replace the OpenConnection2 parameter ctLocalQBD with the parameter ctRemoteQBOE. Of course, you need to register your application with IDN as described in
8
Chapter 1: Introduction
(c) 2004 Intuit Inc. All rights reserved.

the Developers Guide for QuickBooks Online Edition, and you need to install the QBOE connector provided with the SDK. (This is redistributable via the standalone installer or merge module.) Notice that you must make the call to BeginSession.
NOTE You could alternatively integrate the sample program shown in Listing 1-1 with QuickBooks Online Edition, using QBOESessionManager instead of QBSessionManager. (See Using the Session Manager to Communicate with QuickBooks (page 29). In the listing you could retain the calls to OpenConnection and BeginSession, but they would have no effect on QBOESessionManager and simply return an HRESULT of S_OK. The BillAdd sample, which is located in the \samples\qbdt\vb\qbfc\billadd folder, provides an example of this technique.
Integrating This Sample with Multiple Countries

To change the sample program shown in Listing 1-1 so that it will integrate with either U.S. or Canadian editions of QuickBooks: 1. As already described, create an instance of QBSessionManager, open a connection, and begin a session. 2. Before moving on to 2. Build a request set on page 9, call the QBXMLVersionsForSession method to determine which country edition of QuickBooks, U.S. or Canadian, is open. 3. In 3. Send the request set to QuickBooks on page 11, create a request message set that passes the appropriate country information. For example:
CreateMsgSetRequest ("CA",3,0)

Add some request messages and fields using the knowledge of what country the requests are being sent to, then send the request to QuickBooks. 4. Parse the response from QuickBooks using the knowledge of what country you are integrating with. 5. End the session and close the connection to the company file. For more information, see Appendix B, Integrating with Canadian Editions of QuickBooks. 2. Build a request set Your application sends request messages to QuickBooks, and QuickBooks sends response messages back to your application. Because more than one message can be sent at a time, one or more messages are always grouped within a message set: The request message set (or simply the request set) is called IMsgSetRequest in QBFC. It corresponds to QBXMLMsgsRq in qbXML. The response message set (or simply the response set) is called IMsgSetResponse in QBFC. It corresponds to QBXMLMsgsRs in qbXML.

The Process of Interacting with QuickBooks


(c) 2004 Intuit Inc. All rights reserved.

To build a message set, acquire the IMsgSetRequest object by calling the session managers CreateMsgSetRequest method, as shown in these two lines from Listing 1-1. It is here that you decide which qbXML version you want the request set to have:
Dim requestSet As QBFC4Lib.IMsgSetRequest Set requestSet = sessionManager.CreateMsgSetRequest("US",4, 0)

NOTE Be careful setting the CreateMsgSetRequest parameters. It affects which versions of QuickBooks your application can communicate with, and the requests you can use. For details, see CreateMsgSetRequest (page 33).

Once you have the message set, you can set attributes in it. To insert a request, you must Append the request to the message set and then set values in the request object, as shown in the snippet below:
Dim customerAdd As QBFC4Lib.ICustomerAdd Set customerAdd = requestSet.AppendCustomerAddRq customerAdd.Name.SetValue Joe customerAdd.CustomerTypeRef.FullName.SetValue "East Coast" requestSet.Attributes.OnError = roeContinue

Notice that the Append call sets the request into the message set object and returns the request object for you to populate with data. What you must be very careful to observe is that every time you call an Append method, you are creating a brand-new request in the message set. For example if you call AppendCustomerRq multiple times, and each time set a different value in its returned ICustomerAdd object, you will have multiple CustomerAdd objects, each of which has a different field set. The result will NOT be to have a single customer with all the fields set.
Appending a Request

The IMsgSetRequest object has a method to add a request for every request defined in qbXML. The name of each of these methods starts with Append, followed by the name of the request. For example, the AppendCustomerAddRq method shown above adds the CustomerAddRq request to the request set. Most Append methods return a corresponding request object, which you then fill with the data needed for that request. At minimum, you must set all of the objects required fields. In the example above, two fields are set in the ICustomerAdd object, Name (which is required) and CustomerTypeRef (which is optional). To determine which fields are required for any request object, you can use the Onscreen Reference.
IMPORTANT When you build a request, you may call its Append method only once. This appends the request to the message set. To fill in the request with required and optional data, you must set any desired fields in the request object that is returned from the Append call. 10 Chapter 1: Introduction
(c) 2004 Intuit Inc. All rights reserved.

For more details about Append methods, see How to Append Requests to the Request Message (page 61).
Setting Attributes

Finally, before you can send the request set to QuickBooks, you must set its onError attribute. This value indicates whether or not you want QuickBooks to continue processing requests if it encounters an error with one of the requests. This value will not matter when there is only one request, but you still must set it. For more details about setting attributes, see Attributes (page 59) and IAttributesRqSet (page 63). 3. Send the request set to QuickBooks Once your application has initiated a session with a QuickBooks company file and constructed a set of one or more requests, it can send the request set to QuickBooks for processing. As with all QBFC communication with QuickBooks, this relies on the session manager object, and, specifically, its DoRequests method shown here:
Dim responseSet As QBFC4Lib.IMsgSetResponse Set responseSet = sessionManager.DoRequests(requestSet)

DoRequests takes the request message set as a parameter and returns the response message set from QuickBooks, except when something prevents QuickBooks from interpreting or executing the requests in the request set. In these cases, for example when trying to call DoRequests without successfully calling BeginSession first, DoRequests fails with an error HRESULT. Before the requests in the request set are forwarded to QuickBooks, they are verified against the standards defined by qbXML. This ensures, for example, that the requests arent missing anything thats required. If the verification fails for some reason, then DoRequests fails with an error HRESULT. For more details, see DoRequests (page 34).
NOTE After calling DoRequests, if you want to build a new request set that doesnt contain the requests (and attributes) in the current one, you can do one of two things: Call ClearRequests (page 60) from the IMsgSetRequest object. Call CreateMsgSetRequest again on QBSessionManager or QBOESessionManager object to build a new request.

4. Check response status and data If DoRequests succeeds, it returns a response set containing one response for every request in the original request set. Each of these responses holds status information, and possibly data, returned from QuickBooks based on its processing of the corresponding request.

The Process of Interacting with QuickBooks 11


(c) 2004 Intuit Inc. All rights reserved.

Once again, consider the related part of the sample program shown in Listing 1-1:
Dim response As QBFC4Lib.IResponse Set response = responseSet.ResponseList.GetAt(0) If (response.StatusCode <> 0) Then MsgBox "Status: Code = " & CStr(response.StatusCode) & _ ", Severity = " & response.StatusSeverity & _ ", Message = " & response.StatusMessage End If Dim customerRet As QBFC4Lib.ICustomerRet Set customerRet = response.Detail If Not (customerRet Is Nothing) Then MsgBox "CustomerRet ListID = " & customerRet.ListID.GetValue End If If Not (customerRet.BillAddress Is Nothing) Then If Not (customerRet.BillAddress.State Is Nothing) Then MsgBox "The customer is billed in " & _ customerRet.BillAddress.State.GetValue End If End If

NOTE The property called ResponseList contains the responses as a list, even if the list has only one element. For more details, see ResponseList (page 67) and IResponseList (page 68). For an example where ResponseList returns more than one response, refer to the MultipleRequests sample program in the \samples\qbdt\vb\qbfc or \samples\qbdt\cpp\qbfc folder. To download the samples and the rest of the SDK, visit http://developer.intuit.com/QuickBooksSDK/Downloads/.
Checking the Status Information

If the status code of any response is not 0 (zero), you should examine the status information in more detail to determine the proper course of action. (The example above just displays the information.) The status code indicates precisely what happened, while the status severity indicates its general level of importance: Info, Warn (for Warning), or Error. For a complete list of status codes, their severities, and their messages, refer to the Onscreen Reference. Sometimes looking at the status information is all you need to do after issuing a request. Other times you will also be interested in the data that QuickBooks might return: If the status code is 0, you are assured of having data in the Detail property of the response object. If the status code is anything other than 0, its exact value will determine the existence of any return data. Instead of checking the exact value of the status code, your application can check whether the responses Detail property is not NULL. (Or, as shown above, in VB you can check whether the property is not Nothing.)

12 Chapter 1: Introduction
(c) 2004 Intuit Inc. All rights reserved.

Retrieving the Data

In the Detail property, QuickBooks will return one of two forms of data: For most Query requests, it will return a list of Ret (Return) objects. For Add, Mod, Del, and Void requests, and for HostQuery and PreferencesQuery requests, it will return a list containing a single Ret object, as in the example above.

To see how to handle a list of Ret objects, refer to either the InvoiceQuery or ItemQuery sample program in the \samples\qbdt\cpp or \samples\qbdt\cpp folders. (To download the samples and the rest of the SDK, visit http://developer.intuit.com/QuickBooksSDK/ Downloads/.) Usually, the type of Ret object returned matches the type of data in the request. In the sample program shown in Listing 1-1, Customer is the type of data in the request, so Customer is the type of Ret object in the response.
Dim customerRet As QBFC4Lib.ICustomerRet Set customerRet = response.Detail If Not (customerRet Is Nothing) Then MsgBox "CustomerRet ListID = " & customerRet.ListID.GetValue End If If Not (customerRet.BillAddress Is Nothing) Then If Not (customerRet.BillAddress.State Is Nothing) Then MsgBox "The customer is billed in " & _ customerRet.BillAddress.State.GetValue End If End If

For more information about the types of Ret objects that the Detail property can return, see Detail (page 70). For more information about Ret objects in general, see Ret Objects (page 78). 5. Relinquish the communication channel with QuickBooks Once you are done interacting with a specific desktop QuickBooks company file, you can relinquish the communication channel you have with it by calling the session managers EndSession method. Once you are no longer interacting with any QuickBooks company file, you can call the session managers CloseConnection method. The proper use of these methods is to call EndSession first, as shown in Listing 1-1:
sessionManager.EndSession sessionManager.CloseConnection

To prevent other applications from being locked out of a company file, QBFC will automatically call both EndSession and CloseConnection when the QBSessionManager object goes out of scope.

The Process of Interacting with QuickBooks 13


(c) 2004 Intuit Inc. All rights reserved.

qbXML Data Types in QBFC


In QBFC, each qbXML data type has been mapped to its own object, which is a wrapper for a COM data type. By having individual data type objects, the QBFC Library is able to enforce data type restrictions, thereby preventing you from assigning invalid values. For example, if you try to assign 41.333 to an IQBAmountType object, it will fail because amounts are limited to two decimal places. Table 1-1 shows the mapping between the qbXML data types and the data type objects used in the QBFC Library.
Table 1-1 qbXML data types and corresponding QBFC data type objects QBFC Data Type Objects IQBEN*Type, where * is the name of the specific enum. See Enum Data Types (page 90). IQBAmountType (page 91) IQBBoolType (page 93) IQBDateType (page 93) IQBDateTimeType (page 94) IQBIDType (page 96) IQBIntType (page 97) IQBPercentType (page 98) IQBPriceType (page 99) IQBQuanType (page 100) IQBStringType (page 101) IQBTimeIntervalType (page 102) IQBGuidType (page 102) IQBFloatType (page 95)

qbXML Data Types ENUMTYPE

AMTTYPE BOOLTYPE DATETYPE DATETIMETYPE IDTYPE INTTYPE PERCENTTYPE PRICETYPE QUANTYPE STRTYPE TIMEINTERVALTYPE GUIDTYPE FLOATTYPE

Categories of Objects in QBFC


The word object has a different meaning in the context of the QBFC Library than in the context of the QuickBooks SDK as a whole: In general in the QuickBooks SDK documentation, the term object refers to something in QuickBooks, such as an account, payment, credit, vendor, invoice, or purchase order. Objects in the QBFC Library refer to aggregates, OR constructs, repeating elements, messages, and message sets. Other QBFC objects handle such things as queries and their filters, message set attributes, data types, and session management. There are literally hundreds of objects in QBFC!

14 Chapter 1: Introduction
(c) 2004 Intuit Inc. All rights reserved.

To make QBFC objects easier to understand, they are grouped into categories:
Session Management

The session management objects are used for communicating with QuickBooks. QBSessionManager (which can be used with any SDK-enabled QuickBooks edition, including QBOE) and QBOESessionManager (which can only be used with QBOE) are both described in Chapter 2, Communicating with QuickBooks.
High-Level Event Callback

IEventsMsgSet objects contain callbacks that are triggered by the occurrence of subscribed events in QuickBooks. For more information, see Event Notification (page 54).
High-Level Request Information

These objects, described in Chapter 3, High-Level Request Objects, are used for request information, excluding the actual message content: IMsgSetRequest IAttributesRqSet ISubscriptionMsgSetRequest

High-Level Response Information

These objects, described in Chapter 4, High-Level Response Objects, are used for response information, excluding the actual message content: IMsgSetResponse IResponseList IResponse IAttributesRsSet ISubscriptionMsgSetResponse

Message Data

These objects, described in Chapter 5, Message Data Objects, are used for the actual content of request and response messages: IQBBase, the interface from which all message data objects derive Add, Mod, Del, Void, Ret, and Query objects Basic aggregate objects (including object references) Group objects, which are named collections of fields ORGroups, which include fields or groups of fields that are mutually exclusive QBFC lists, which are repeating fields or repeating groups of fields (In other contexts in this book, the word list refers to the types of listed data in QuickBooks, such as customer and account lists.) Subscription and callback objects for UI integration and event notification

Data Types

These objects, described in Chapter 6, Data Type Objects, are used for qbXML data types: IBasicPropertyType, from which all QBFC data type objects derive
Categories of Objects in QBFC 15
(c) 2004 Intuit Inc. All rights reserved.

IQB*Type, where * represents the name of the specific data type

Using IntelliSense
In the Visual Studio editors (for VB and VC++), you can use IntelliSense to easily find characteristics of QBFC objects, including the methods and properties of an object, as well as the parameters and return value of a method, as shown in the examples below. To use IntelliSense in VC++, save the qbfc4.tlh file generated by the VC compiler in the Debug or Release directory of your project as qbfc4IntelliSense.h, and then add qbfc4IntelliSense.h to the 'Header Files' section of your Project. In VB, type . (or in VC++, type ->) after an object to see that objects methods and properties:

Type ( after a method to see that methods parameters and return value:

NOTE In VB, when a method has only parameters with no return value, you can also type a space after the method to reveal the parameters. Also in VB, when a method has only a return value with no other parameters, you cannot use IntelliSense to see the type of the return value.

Type QBFC4Lib followed by . (in VB only) to see a list of all the possible enum values in QBFC.

16 Chapter 1: Introduction
(c) 2004 Intuit Inc. All rights reserved.

Using the Visual Studio 2003 Plug-in


QBFC4 provides an installer for the SDK VS 2003 plug-in. You can install and use this if you have Visual Studio 2003 installed. The plug-in provides context sensitive help, SDK documentation, OSR, and F1 keyword help from within the Visual Studio IDE. It also provides code samples.

Using the Onscreen Reference


The QuickBooks SDK: Onscreen Reference is an HTML-based reference manual that provides details on message data objects, data types, subscription objects, and the event callback object in QBFC. Also, VB6 and VB.Net sample code is available for each request and response message, and for the event callback message (QBSDKEvents). If you have installed the SDK, you can find the Onscreen Reference in your Start menu. To view the details of a particular message object in the Onscreen Reference, follow these steps: 1. Choose the name of the message from the first list at the top of the screen. The list includes all the request messages associated with the Append methods of the IMsgSetRequest object. or Choose a subscription request or the callback object (QBXMLEvents) from the second list at the top of the screen. 2. Click Request or Response. > If you click Request, the object displayed will be the one returned from the message you chose in Step 1. ORGroup Objects (page 82) shows an example of how to interpret the Onscreen Reference for a QBFC request. If you click Response, the object displayed will be the contents of the Detail property of the IResponse object that QuickBooks returns as a result of the request you chose in Step 1.

>

Each field of the message data object is listed hierarchically, along with its type and any special characteristics it might have. Click any name or type that is shown as a link to see additional information about it in the bottom frame of the window. Click VB6 Code or VB.Net Code to see a Visual Basic sample program that uses QBFC4 to connect to the desktop version of QuickBooks, send the request message that you selected, and handle the response. For direct access to the project files for this sample code, see the QBSDK4.0\OSR\OnscreenRef\SampleCode\VB6 or VB.Net folders. Click Errors to view the following information: > > A description of the StatusCode, StatusSeverity, and StatusMessage properties of the IResponse object. A description of the HRESULT values that QBFC COM calls can return.

Categories of Objects in QBFC 17


(c) 2004 Intuit Inc. All rights reserved.

Click QuickRef to see the methods and properties in the higher-level QBFC objects.

(The main part of the Onscreen Reference shows only the methods and properties for the lower-level objects.)
Click Help for more information, including version and copyright information.

Registering and Signing Your Application


When you have finished developing and testing your application, you can register and digitally sign it: To make it easier for QuickBooks customers to learn about your application, register it with the Intuit Developer Network (IDN) Solutions Marketplace. For more information, visit http://developer.intuit.com/Marketing/. To assure your users that your application code has not been tampered with, you can get a digitally signed certificate for it. For more information, see Chapter 1 of the Developers Guide for QuickBooks.

Distributing Your Application


IMPORTANT The QBFC4 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 QBFC4 stand-alone installer using the SHFolder.exe redistributable installer from Microsoft. If you plan to use the QBFC4 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 QBFC4 merge module itself.

If you are using the QBFC API or the Remote Data Sharing (RDS) feature, there are only two supported ways in which you can distribute our redistributable components: 1. You can use the stand-alone compressed-image installers that we provide. 2. You can use the merge modules that we provide.
NOTE It is a violation of your qbXML license agreement to redistribute QBFC or RDS without using either our stand-alone installers or our merge modules.

18 Chapter 1: Introduction
(c) 2004 Intuit Inc. All rights reserved.

Automatic installation programs and packaging wizards, such as the wizard in Microsoft Visual Studio, will not do the right thing (even if you are using .NET): 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.

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 do the right thing. To install the QBFC4 Library on your end-users machines: Distribute the QBFC installer, QBFC4_0Installer.exe, located in the /QBSDK4.0/tools/installers folder. (Merge modules are in /QBSDK4.0/tools/ MergeModules.) Call the installer. Exactly how you call it depends on the underlying technology you are using to drive your installation.

QBFC1, QBFC2, QBFC2CA, QBFC2_1, QBFC3, and QBFC4 can be installed side-by-side on the same computer. The stand-alone installer for QBFC4 will install QBFC4 and QBXMLRP2. (For more information about QBXMLRP2, see the Technical Overview.)

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 arent 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.

Distributing Your Application 19


(c) 2004 Intuit Inc. All rights reserved.

How Do I Use a Merge Module from the SDK? The SDK merge modules are located in the /tools/MergeModules folder. Heres 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 modulein other words, installing QBFC4 installs the Xerces files and QBXMLRP2.

20 Chapter 1: Introduction
(c) 2004 Intuit Inc. All rights reserved.

CHAPTER 2 COMMUNICATING WITH QUICKBOOKS

1 1

This chapter describes how your application communicates with QuickBooks. It also gives a detailed description of the session manager objects that handle all communication with QuickBooks. The following topics are covered: Authorizing your application, which describes > > The default authorization page Using the new QBAuthPreferences object and methods to inform users of your applications authorization requirements and simplify user selection (new functionality in QBFC4). Setting authorization preferences for your integrated application within QuickBooks (the old way of setting/changing preferences). More information on login modes (auto-login versus interactive login) More information on accessing personal company data More information on single-user versus multi-user mode for accessing a QuickBooks company file

> > > >

The QBSessionManager and QBOESessionManager objects Automated error recovery Event notification

Enabling Users to Authorize Your Application


NOTE This section does not apply to QuickBooks Online Edition.

The first time your application logs in to QuickBooks, QuickBooks must already be launched and running in the foreground and the administrator user must be logged in. These requirements prevent unauthorized applications from gaining access to QuickBooks.

When is the Authorization Dialog Displayed?


As previously noted, the authorization dialog appears when an application tries to access a QuickBooks company file for the first time. The authorization dialog is also displayed when A QuickBooks company file is opened for the first time by an application after it makes an event subscription

Enabling Users to Authorize Your Application


(c) 2004 Intuit Inc. All rights reserved.

21

An application previously authorized to access a particular QuickBooks company file attempts to access that file in a way different than authorized or with different preferences than the last time it accessed that file. (This supports the new SDK 4.0 functionality that allows your application to prompt the user to provide the type of authorization your application needs, for example, unattended mode.

The Default Authorization Dialog


The default authorization dialog that QuickBooks presents to the user is shown in Figure 21 on page 23. In the authorization dialog, the QuickBooks administrator can Refuse authorization by selecting No Authorize for only the current session and force the application to be authorized again the next time the application attempts to access a company file by selecting "Prompt each time" Authorize the application to access QuickBooks with no additional authorization whenever that company file is open, regardless of which user is logged in by selecting Yes, whenever this company file is open.. Authorize the application to log on in unattended mode (auto login) by selecting Yes, allow access even if QuickBooks is not running. > If the user selects unattended mode authorization, and there is more than one user for the QuickBooks company, then the login as dropdown is enabled, presenting the user with a list of login IDs currently able to log in to that company file.

The checkbox at the bottom of the authorization dialog, if checked, authorizes your application to access sensitive personal data. However. the currently logged in user is still restricted by the permissions set up in QuickBooks, regardless of whether or not the checkbox is checked.

22 Chapter 2: Communicating with QuickBooks


(c) 2004 Intuit Inc. All rights reserved.

Figure 2-1

First Time Authorization Form

Using QBAuthPreferences to Obtain Proper Application Authorization


Starting with SDK 4.0, you can use the QBAuthPreferences object to inform the user via the QuickBooks authorization dialog itself, about the level of access that your application requires. Using QBAuthPreferences is recommended because it lets the user know immediately what your application requires, simplifies the users choices by displaying only those authorization selections in the dialog that are relevant, and eliminates the need to navigate through multiple QuickBooks menus and dialogs. Notice that you must be logged in as the QuickBooks administrative user before you actually change the preferences: otherwise youll get an error. The QBAuthPreferences object has three write methods, which must be invoked BEFORE the call to BeginSession: PutIsReadOnly (VARIANT_BOOL isReadOnly). This causes the QuickBooks authorization dialog to display text informing the user that its access will be read-only.

Enabling Users to Authorize Your Application


(c) 2004 Intuit Inc. All rights reserved.

23

PutUnattendedModePref (ENUnattendedModePrefType unattendedModePref). This has different effects depending on the parameter specified: > umptRequired, which causes the QuickBooks authorization dialog to display only the selection choices of No (no authorization) or Yes, allow access even if QuickBooks is not running (authorize unattended mode). umptOptional, which causes the QuickBooks authorization dialog to display its default selections.

>

PutPersonalDataPref(ENPersonalDataPrefType personalDataPref) which has different effects depending on the parameter specified: > pdptRequired, which causes the QuickBooks authorization dialog to not display the personal information checkbox for user selection, and instead display a warning that the application must access personal data such as SSN or credit card information. pdptOptional, which causes the QuickBooks authorization dialog to display a checkbox for user selection asking whether the user wants to allow the application to access personal data such as SSN or credit card information. pdptNotNeeded, which causes the QuickBooks authorization dialog to not display the personal information checkbox for user selection, and instead display an informational message that the application will NOT access personal data such as SSN or credit card information.

>

>

There are three Get methods (GetIsReadOnly, GetUnattendedModePref, and GetPersonalDataPref) that return the authorization preferences currently in effect, but these methods can only be invoked AFTER the call to BeginSession.
IMPORTANT Your code implementing the new authorization capabilities will not run on QB versions earlier than QuickBooks 2005. However, no errors will occur, so you can safely write code and expect no failures. However, you should do a check, using the new (in QBFC4) QBAuthPreferences method WasAuthPreferencesObeyed to determine whether the authorization preferences were successfully set.

Setting Authorization Preferences Within QuickBooks


If your application does not use the QBAuthPreferences object and methods to help the QuickBooks administrator set authorizations properly, the QuickBooks administrator may need to set additional authorization preferences or change existing authorization preferences for integrated applications within QuickBooks by clicking on the Integrated Applications icon in the QuickBooks Preferences window, then selecting Company Preferences. Preferences that can be set by the administrator include the following: Disallowing or changing application access Enabling certificate date checking

24 Chapter 2: Communicating with QuickBooks


(c) 2004 Intuit Inc. All rights reserved.

Listing authorized applications Granting auto-login privileges and assigning the name of the auto-login user Allowing application access to personal company data

Figure 2-2 shows the window presented to the administrator for managing integrated applications and their access to QuickBooks.

Figure 2-2

QuickBooks window for setting Company Preferences

More Information about Login Modes


Integrated applications can log in to QuickBooks in one of two modes: In interactive mode, QuickBooks runs in the foreground, and its user interface is displayed. The user logs in to QuickBooks and opens a company file. Subsequently, your application is launched and attaches to the company file that has already been opened. The user can interact directly with your application and with QuickBooks. In unattended mode (auto-login), QuickBooks runs in the background, and its user interface may or may not be displayed, depending on the connection type you specify in the call to OpenConnection2. The ctLocalQBD type either uses the local QuickBooks currently running or, if not running, launches QB in unattended mode (without UI, thus non interactively). If QuickBooks is not running, the ctLocalQBDLaunchUI type launches it in interactive mode (the UI is displayed). If
Enabling Users to Authorize Your Application
(c) 2004 Intuit Inc. All rights reserved.

25

your connection type doesnt specify the launching of the QuickBooks UI, then QuickBooks features are fully available to your application but not to the user. Notice that whenever QuickBooks is started by the application rather than by the smallbusiness owner, it is in auto-login mode. Setting Up Auto-Login As described in the preceding section, you use the QBAuthPreferences object to inform the user that auto-login (unattended) mode is required. The proper dialog with the auto-login prompt will be presented to the user for confirmation (or not). Alternatively, you can set up auto-login from within QuickBooks. Using this method, the QuickBooks administrator sets the user name under which your application will run in QuickBooks under Company Preferences, Properties, Access Rights, a window that is accessible only to QuickBooks administrators (see Figure 2-3).

Figure 2-3

QuickBooks window for allowing auto-login by an integrated application

If you use this (older) method, be sure to tell your user that the QuickBooks administrator must give your application the necessary user access permissions required for auto-login. Only One Auto-Login User per Application Regardless of whether single-user or multi-user mode is specified for a given session, there can be only one auto-login active during that session. Figure 2-4 illustrates a multi-user session, with four different users accessing the same company file. Because Joe is designated as an auto-login user on System 4, no other users can log in automatically until

26 Chapter 2: Communicating with QuickBooks


(c) 2004 Intuit Inc. All rights reserved.

Joe (the auto-user) logs out. When multiple instances of an integrated application are running on different systems and accessing the same company file, as shown in Figure 2-4, each user must have a different name.
System 1 User: Sam (interactive login)

QuickBooks
Joes Bakery

System 2 User: Jane (interactive login) System 3 User: Everett (interactive login) System 4 User: Joe (auto-login)

Figure 2-4

Multiple users accessing the same company file

More Information on Accessing Personal Data


The Access Rights window shown in Figure 2-3 also includes a check box that allows your application access to personal data in the company file. Personal data can include: Employee social security numbers Any field directly related to an employees salary Anything related to credit card numbers and bank account numbers

Be sure to instruct the QuickBooks administrator to check this box if your application requires access to personal employee data. (Alternatively, your application can require access to personal data using the QBAuthPreferences object, which is available for QuickBooks 2005 and later.)

More Information on Single-User vs. Multi-User Mode


During a QuickBooks session, your application specifies whether to open the company data file in single-user or multi-user mode. It is important to balance your needs with the overall implications of selecting one mode over the other. Table 2-1 on page 28 summarizes the different combinations. Note that if an integrated application opens a company file in single-user mode, no other applications or users can work on that company file during that session. In some cases, this mode may be necessary, but in others it may be bad citizenship. Another interesting case is that even when the integrated application opens a company file in multi-user mode, other integrated applications can access the company file, but no actual users can access that company file on the same system.

Enabling Users to Authorize Your Application


(c) 2004 Intuit Inc. All rights reserved.

27

Table 2-1

QuickBooks company file login mode access conditions and rights Mode Single-user Who can obtain access No one else

Who started QuickBooks Integrated Application

Integrated Application

Multi-user

QB users on same machine = no access All other integrated applications = access QB users on other machines = access

QuickBooks User

Single-user

QB user already logged in Only one integrated application = access

QuickBooks User

Multi-user

QB users = access Integrated applications = access

Trade-offs of Using Single-User Mode Here are some of the advantages and disadvantages of using single-user mode. Advantages: Certain QuickBooks features require that a user operate in single-user mode. For instance, a company file must be open in single-user mode for you to delete any of its list items. Locking and opening protection. If the company file is not already opened by another QuickBooks-integrated application, your application will be able to open it with exclusive access (locking out other applications), gaining improved performance.

Disadvantages: Lockout. If your application attempts to open a company file in single-user mode and that company file is already open in multi-user mode, your application will not be able to access the company data file. Your application will be locked out. (If your application specifies multi-user mode, it can share access to the company file.) Exclusion of other applications. Your application locks out other applications, denying them access to the company file. This behavior is considered impolite. In environments that are known to need multi-user access, this might be of some concern.

28 Chapter 2: Communicating with QuickBooks


(c) 2004 Intuit Inc. All rights reserved.

Using the Session Manager to Communicate with QuickBooks


The session manager interfaces are considered the top-level objects in QBFC. They handle all communication with QuickBooks (including acquiring permission to access a QuickBooks company file in the first place), and they create the IMsgSetRequest object, which you use for all your requests. There are two session manager interfaces: The QBSessionManager object handles communication between desktop applications and desktop versions of QuickBooks (both U.S. and Canadian editions), and, beginning with QBFC4, also handles communication with QuickBooks Online Edition via the connection type parameter in the new OpenConnection2 call. The QBOESessionManager object handles communication between desktop applications and QuickBooks Online Edition. This object continues to be supported in QBFC4, but the use of the QBSessionManager with the new OpenConnection2 call is easier to use, if you are considering writing or porting an application for QBOE.

NOTE Both QBSessionManager and QBOESessionManager support the IErrorInfo interface, so you can use IErrorInfo to get more information about most of the HRESULT values that the QBFC methods and properties return.

Table 2-2 and Table 2-3 show methods and properties in the QBSessionManager and QBOESessionManager objects.
Table 2-2 QBSessionManager (page 1 of 3) Use Creates IMsgSetRequest object. Sends IMsgSetRequest object to QuickBooks. Returns the QBFC version. Parses message response from QuickBooks. Like DoRequests, but takes an XML string. For automated error recovery. For automated error recovery. For automated error recovery. For automated error recovery. For automated error recovery. For automated error recovery. For automated error recovery. For automated error recovery.

QBSessionManager Function CreateMsgSetRequest (page 33) DoRequests (page 34) GetVersion (page 34) ToMsgSetResponse (page 35) DoRequestsFromXMLString (page 36) ToMsgSetRequest (page 36) IsErrorRecoveryInfo (page 36) ClearErrorRecovery (page 37) EnableErrorRecovery (page 37) ErrorRecoveryID (page 37) SaveAllMsgSetRequestInfo (page 37) GetErrorRecoveryStatus (page 38) GetSavedMsgSetRequest (page 38)

Using the Session Manager to Communicate with QuickBooks


(c) 2004 Intuit Inc. All rights reserved.

29

Table 2-2

QBSessionManager (page 2 of 3) Use New in QBFC4. Establishes a connection with QuickBooks using the specified connection type (local QB, remote QB--RDS, local QB with UI for unattended mode, or QBOE). The older OpenConnection method is still supported.

QBSessionManager Function OpenConnection2

CloseConnection (page 39) BeginSession (page 39) EndSession (page 41)

Closes the connection with QuickBooks. Begins a session with a QuickBooks file. Ends a session.

GetCurrentCompanyFileName (page 42) Returns the name of the QuickBooks file. QBXMLVersionsForSession (page 42) CreateSubscriptionMsgSetRequest (page 43). DoSubscriptionRequestsFromXMLString (page 44) ToSubscriptionMsgSetResponse (page 44) DoSubscriptionRequests (page 45) Returns supported qbXML versions. For event notification. For event notification. For event notification. For event notification.

30 Chapter 2: Communicating with QuickBooks


(c) 2004 Intuit Inc. All rights reserved.

Table 2-2

QBSessionManager (page 3 of 3) Use For event notification. Returns information about the QuickBooks request processor. New in QBFC4. Identifies the qbXML spec versions supported for subscription activity. New in QBFC4. Provides out of process communication. Previous to SDK 4.0 this was provided externally via qbXMLRP2e but now you may invoke this functionality from within QBFC. This call is useful when your application must run as part of a windows service process and therefore does not have permission to communicate with QuickBooks in-process as it usually would.

QBSessionManager Function ToEventsMsgSet (page 45) ConnectionType (page 46) QBXMLVersionsForSubscription CommunicateOutOfProcess

Functions of QBAuthPreferences

New in QBFC4. This is a Property of the QBSessionManager object that indicates the authorization requirements of the application. This property has the following methods: GetIsReadOnly. Determines whether your application has specified that it is read-only. PutIsReadOnly. Specifies whether your application is read-only. GetUnattendedModePref. Determines whether your application has specified that it requires unattended mode. PutUnattendedModePref. Specifies whether your application requires unattended mode. GetPersonalDataPref. Determines whether your application has specified that it requires access to personal data. PutPersonalDataPref. Specifies whether your application requires access to personal data. WasAuthPreferencesObeyed. Determines whether the QBAuthPreferences property and methods are supported by the QuickBooks currently running

Using the Session Manager to Communicate with QuickBooks


(c) 2004 Intuit Inc. All rights reserved.

31

Table 2-3

QBOESessionManager Use Creates IMsgSetRequest object. Sends IMsgSetRequest object to QuickBooks. Returns the QBFC version. Parses message response from QuickBooks. Like DoRequests, but takes an XML string. For automated error recovery. For automated error recovery. For automated error recovery. For automated error recovery. For automated error recovery. For automated error recovery. For automated error recovery. For automated error recovery. Only needed for QuickBooks Online Edition. Only needed for QuickBooks Online Edition. Only needed for QuickBooks Online Edition. Only needed for QuickBooks Online Edition. Only needed for QuickBooks Online Edition. Only needed for QuickBooks Online Edition. Only needed for QuickBooks Online Edition. Only needed for QuickBooks Online Edition.

QBOESessionManager Function CreateMsgSetRequest (page 33) DoRequests (page 34) GetVersion (page 34) ToMsgSetResponse (page 35) DoRequestsFromXMLString (page 36) ToMsgSetRequest (page 36) IsErrorRecoveryInfo (page 36) ClearErrorRecovery (page 37) EnableErrorRecovery (page 37) ErrorRecoveryID (page 37) SaveAllMsgSetRequestInfo (page 37) GetErrorRecoveryStatus (page 38) GetSavedMsgSetRequest (page 38) ApplicationLogin (page 51) ConnectionTicket (page 51) InstallationID (page 51) Language (page 52) AppID (page 52) AppVer (page 52) SessionTicket (page 52) AuthID (page 52)

32 Chapter 2: Communicating with QuickBooks


(c) 2004 Intuit Inc. All rights reserved.

Functions of QBSessionManager and QBOESessionManager


These functions are used for communication both with desktop versions of QuickBooks and with QuickBooks Online Edition.

CreateMsgSetRequest
HRESULT CreateMsgSetRequest ([in] BSTR country, [in] short qbXMLMajorVersion, [in] short qbXMLMinorVersion, [out, retval] IMsgSetRequest** request)

Tells QBFC which version of qbXML your application is using, and receives the request message set object in return. Notice that starting with QBFC3, CreateMsgSetRequest requires all three parameters.
Parameters

country

The country of the edition of QuickBooks to be used by your application. There are three valid values: "US", "CA", and "" (empty string). (You can use an empty string if your application is connecting with QuickBooks Online Edition.)

qbXMLMajorVersion The major version of qbXML to be used by your application. (For example, if the version is 2.1, the major version is 2.) qbXMLMinorVersion The minor version of qbXML to be used by your application. (For example, if the version is 2.1, the minor version is 1.) request
NOTE QBFC4 supports qbXML versions 1.0, 1.1, 2.0, 2.1, 3.0, and 4.0 for the U.S. QBFC4 supports versions 2.0 and 3.0 for Canada.
Usage

The request message set object, to which you will add one or more request messages.

It is important to set the qbXML version appropriately: Make sure all your end-users have a version of QuickBooks installed on their computers that supports the qbXML version you specify. Note that you cannot use any qbXML functionality that was added since the version you specify. An error code of 0x8004030A will be returned if the given version of qbXML is not supported by the version of QBFC being used.

HRESULT Error Codes

Functions of QBSessionManager and QBOESessionManager


(c) 2004 Intuit Inc. All rights reserved.

33

DoRequests
HRESULT DoRequests ([in] IMsgSetRequest* request, [out, retval] IMsgSetResponse** responseSet)

Sends the specified XML request to QuickBooks and returns a response.


Parameters

request responseSet
Usage

The request message set object containing any number of requests to be processed by QuickBooks. The parsed response message set object, which will contain a list of responses, one for every request in the request message set.

Before sending the request set to QuickBooks for processing, this method verifies the given request message set to make sure that all the mandatory fields in each of its requests have been set and that no two mutually exclusive fields have been set.
HRESULT Error Codes

An error code of 0x80040307 will be returned if there is an error verifying the requests in the request set. An error code of 0x8004040C will be returned if no valid session currently exists. An error code of 0x80040423 will be returned if the given version of qbXML is not supported by the QuickBooks SDK. An error code of 0x8004030C will be returned if DoRequests is used with QBSessionManager when it can only be used with QBOESessionManager, or if it is used with QBOESessionManager when it can only be used with QBSessionManager. When DoRequests is called in the context of QBOESessionManager, an error code of 0x8004030D will be returned if an HTTP-specific error occurs.

For more errors that DoRequests can return, see Appendix A, Error Codes.

GetVersion
HRESULT GetVersion ([out] short* majorVersion, [out] short* minorVersion, [out] ENReleaseLevel* releaseLevel, [out] short* releaseNumber)

Returns version and release information for the QBFC Library.


Parameters

majorVersion minorVersion

The major version for the QBFC Library. For example, for QBFC4 the major version is 4. The minor version for the QBFC Library. For example, for QBFC4 the minor version is 0.)

34 Chapter 2: Communicating with QuickBooks


(c) 2004 Intuit Inc. All rights reserved.

releaseLevel releaseNumber

The release level for the QBFC Library. It can be one of four values: rlPreAlpha, rlAlpha, rlBeta, or rlRelease. The release number for the QBFC Library. It corresponds to a specific build of the product software.

ToMsgSetResponse
HRESULT ToMsgSetResponse ([in] BSTR qbXMLResponse, [in] BSTR country, [in] short qbXMLMajorVersion, [in] short qbXMLMinorVersion, [out, retval] IMsgSetResponse** responseSet)

Parses the XML response and returns it in a response message set object.
IMPORTANT This method performs NO version or qbXML validation of the supplied XML string. You are responsible for supplying a valid string to this method call.
Parameters

country qbXMLResponse

The country of the edition of QuickBooks. The qbXML response document (as a string) that gets returned from QuickBooks after processing a request message set sent via the qbXML request processor. Each response in the qbXMLResponse string must have a requestID attribute, and these requestIDs must be consecutive, starting at 0.

qbXMLMajorVersion The major version of qbXML to be used for this operation. (For example, if the version is 2.1, the major version is 2.) qbXMLMinorVersion The minor version of qbXML to be used for this operation. (For example, if the version is 2.1, the minor version is 1.) responseSet
NOTE QBFC4 supports qbXML versions 1.0, 1.1, 2.0, 2.1, 3.0, and 4.0.
HRESULT Error Codes

The response message set object, which will contain a list of responses, one for every request in the request message set.

An error code of 0x80040301 will be returned if there is an internal error interpreting qbXMLResponse. An error code of 0x8004030A will be returned if the given version of qbXML is not supported by QBFC.

Functions of QBSessionManager and QBOESessionManager


(c) 2004 Intuit Inc. All rights reserved.

35

DoRequestsFromXMLString
HRESULT DoRequestsFromXMLString([in] BSTR qbXMLRequest, [out, retval] IMsgSetResponse** responseSet);

Sends an XML request as a string rather than in an IMsgSetRequest object (as happens in DoRequests). Parameters qbXMLRequest responseSet The request is not validated before it is sent. Any requestIDs within the request must start with 0 and continue with 1, 2, and so on. A parsed list of responses, one for every request in the request message set. The responseSet will contain errors if the qbXMLRequest string contains nonsequential requestIDs.

HRESULT Error Codes

When DoRequestsFromXMLString is called in the context of QBOESessionManager, an error code of 0x8004030D will be returned if an HTTP-specific error occurs.

ToMsgSetRequest
HRESULT ToMsgSetRequest( [in] BSTR qbXMLRequest, [out, retval] IMsgSetRequest** requestSet);

Takes qbXML request text and parses it into an IMsgSetRequest object. Reads the qbXML major and minor version numbers from the request.

IsErrorRecoveryInfo
]

HRESULT IsErrorRecoveryInfo( [out, retval] VARIANT_BOOL* bIsErrorRecoveryInfo);

Returns true or false depending on whether error-recovery information is stored on the disk for this application/company-file pair (or application/connection-ticket pair, in the case of QuickBooks Online Edition). For more information about QBFC error recovery, see Automated Error Recovery on page 53.

36 Chapter 2: Communicating with QuickBooks


(c) 2004 Intuit Inc. All rights reserved.

ClearErrorRecovery
HRESULT ClearErrorRecovery();

Clears any error-recovery data on disk and the message set status in the company file for the current company file and integrated application. For more information about QBFC error recovery, see Automated Error Recovery on page 53.

EnableErrorRecovery
HRESULT EnableErrorRecovery([in] VARIANT_BOOL bEnable); HRESULT EnableErrorRecovery([out,retval] VARIANT_BOOL* bEnable);

Indicates whether the error-recovery feature of QBFC is enabled. If error recovery is disabled (the default), requests are sent to QuickBooks without first checking if a response from a previous request was not processed. If error recovery is enabled, requests will not be sent to QuickBooks if an unprocessed response exists for a previous request. For more information about QBFC error recovery, see Automated Error Recovery on page 53.

ErrorRecoveryID
HRESULT ErrorRecoveryID([out, retval] IQBGUIDType* *pVal);

Returns this applications error-recovery ID, which will be used to store the applications error-recovery information to disk. For more information about QBFC error recovery, see Automated Error Recovery on page 53.

SaveAllMsgSetRequestInfo
HRESULT SaveAllMsgSetRequestInfo([in] VARIANT_BOOL bSaveAll); HRESULT SaveAllMsgSetRequestInfo([out,retval] VARIANT_BOOL* bSaveAll);

Indicates whether the error-recovery feature of QBFC should save the entire set of information for a MsgSetRequest: If SaveAllMsgSetRequestInfo is true, the entire contents of the MsgSetRequest is saved to disk for error recovery. If SaveAllMsgSetRequestInfo is false (the default), only the NewMessageSetID is saved.

Functions of QBSessionManager and QBOESessionManager


(c) 2004 Intuit Inc. All rights reserved.

37

For more information about QBFC error recovery, see Automated Error Recovery on page 53. Get/Set VARIANT_BOOL which specifies whether to save the entire MsgSetRequest information. Return HRESULT

GetErrorRecoveryStatus
HRESULT GetErrorRecoveryStatus( [out, retval] IMsgSetResponse** responseSet);

Gets the response status of an unprocessed response. Sends a status check request to QuickBooks to get the status of the request that was stored to disk. The status check response will be returned in an IMsgSetResponse object. For more information about QBFC error recovery, see Automated Error Recovery on page 53.

GetSavedMsgSetRequest
HRESULT GetSavedMsgSetRequest( [out, retval] IMsgSetRequest** requestSet);

Reads the error recovery information (the original message request) that was stored to disk into an IMsgSetRequest object and returns this object. For more information about QBFC error recovery, see Automated Error Recovery on page 53.

Functions of QBSessionManager
The functions shown below (along with those listed in Functions of QBSessionManager and QBOESessionManager) are used for communication with desktop versions of QuickBooks.

OpenConnection2
HRESULT OpenConnection2 ([in] BSTR appID, [in] BSTR appName, [in] ENConnectionType connType)

Establishes a connection between QuickBooks and the client application.


Parameters

appID

Normally not assigned. Use an empty string for appID.

38 Chapter 2: Communicating with QuickBooks


(c) 2004 Intuit Inc. All rights reserved.

appName

The application name used in the log file, in the authorization dialog box, and in menu extensions. This parameter cannot be NULL or an empty string. If you are connecting to QuickBooks Online Edition, the value you supply here must match the AppName value written to the Windows registry, as described in the Developers Guide for QuickBooks Online Edition.) Specify a value of ctUnknown, ctLocalQBD, ctRemoteQBD, ctLocalQBDLaunchUI, or ctRemoteQBOE.

connType
Usage

During the connection process, QuickBooks checks whether your application contains a valid digital signature, which indicates that the application has been certified as trusted. Each call to OpenConnection2 has a small performance cost, so your application, when appropriate, should allow its users to run multiple sessions in a single connection. QuickBooks does not limit the number of consecutive sessions that can be held in a single connection or the length of time a connection can exist. If you specify a connType of ctRemoteQBOE, you can connect to a QBOE company. You should read the Developers Guide for QuickBooks Online Edition for further information, however.
HRESULT Error Codes

When OpenConnection2 is called on QBOESessionManager, it will do nothing and return S_OK. An error code of 0x80040308 will be returned if QBFC cannot communicate with the QuickBooks SDK. An error code of 0x80040309 will be returned if the QuickBooks SDK is a pre-release version.

For more errors that OpenConnection2 can return, see Appendix A, Error Codes.

CloseConnection
HRESULT CloseConnection ()

Closes the connection with QuickBooks. When the QBSessionManager object goes out of scope, QBFC will automatically call CloseConnection if it wasnt called explicitly before. (It also calls EndSession, if necessary.) When CloseConnection is called on QBOESessionManager, it will do nothing and return S_OK.

BeginSession
HRESULT BeginSession ([in] BSTR qbFile, [in] ENOpenMode openMode) Functions of QBSessionManager 39
(c) 2004 Intuit Inc. All rights reserved.

Begins a session working on the specified QuickBooks company file in the specified mode.
Parameters

qbFile

Pathname of the specified QuickBooks company file, or NULL, or an empty string. qbFile as NULL or empty string: If QuickBooks is already launched with an open company file, qbFile can be NULL or an empty string, and your application will attempt to attach to this open file. If no file is open, an error occurs. (If this call succeeds with NULL or an empty string for this parameter, you can obtain the name of the currently open company file by calling GetCurrentCompanyFileName.) qbFile as an actual company file name: If you specify a company file name for qbFile, it might be possible to access that file if it is currently running in QuickBooks (the interactive login option) or if it isnt (the automatic login option). This depends on which login option the end-user has chosen. If QuickBooks is already running, qbFile must exactly match the name used in QuickBooks. For more information, see More Information about Login Modes (page 25), and Permissions Required for Auto-Login (page 80).

openMode

The access mode in which QuickBooks will open the company file. It can be one of three values: omSingleUser, omMultiUser, or omDontCare. The implications associated with each of these access modes are described in More Information on Single-User vs. MultiUser Mode (page 27).

Usage

When your application calls BeginSession on QBSessionManager, the QuickBooks user interface authentication process will be initiated if your application does not already have permission to access the specified company file, and this company file is currently running in QuickBooks.

The authentication process enables a QuickBooks user with administrator privileges to grant your application access permission. If the specified company file is not currently running in QuickBooks, then your application must already have permission to access it.
NOTE If QuickBooks is currently running one company file, you cannot access a different company file with BeginSession.

In auto-login mode it takes several seconds to start QuickBooks and return from a BeginSession call.

40 Chapter 2: Communicating with QuickBooks


(c) 2004 Intuit Inc. All rights reserved.

If QuickBooks is already running, each call to BeginSession has a small performance cost, so your application should allow its users to access the current company file (through DoRequests, for example) as many times as needed in a single session. QuickBooks does not limit the number of times a company file can be accessed in a single session or the length of time a session can exist. Exception: If youre running in single-user mode, no other application will be able to access the current company file until you end the session. In this case, you will want to keep the session as brief as possible. For more information, see Trade-offs of Using Single-User Mode (page 28). For more information about BeginSession, see BeginSession Checks and Tasks (page 77).
HRESULT Error Codes

When BeginSession is called on QBOESessionManager, it will do nothing and return S_OK. An error code of 0x8004040A will be returned if there is already a company data file open and it is different from the requested one. An error code of 0x80040410 will be returned if the company data file is currently open in a mode other than the one specified by your application. An error code of 0x80040414 will be returned if QuickBooks is currently locked in a modal state and cannot be accessed. An error code of 0x8004041B will be returned if QuickBooks is unable to lock the necessary information to allow your application to access the specified company data file. Try again later. An error code of 0x80040422 will be returned if your application is trying to access QuickBooks in single-user mode, but there is another application already accessing the specified company data file.

For more errors that BeginSession can return, see Appendix A, Error Codes.

EndSession
HRESULT EndSession ()

Terminates the session with the current company data file. When the QBSessionManager object goes out of scope, QBFC will automatically call EndSession if it wasnt called explicitly before. (It also calls CloseConnection, if necessary.) If a company file was opened in auto-login mode, EndSession will close the file and enable an interactive user to start QuickBooks on that computer. When EndSession is called on QBOESessionManager, it will do nothing and return S_OK.

Functions of QBSessionManager 41
(c) 2004 Intuit Inc. All rights reserved.

GetCurrentCompanyFileName
HRESULT GetCurrentCompanyFileName ([out, retval] BSTR* pFileName)

Returns the name (including path) of the QuickBooks company data file being accessed in the current session.
HRESULT Error Codes

When GetCurrentCompanyFileName is called on QBOESessionManager, it will do nothing and return S_OK. An error code of 0x8004040C will be returned if no valid session currently exists.

For more errors that GetCurrentCompanyFileName can return, see Appendix A, Error Codes.

QBXMLVersionsForSession
HRESULT QBXMLVersionsForSession ([out, retval] SAFEARRAY (BSTR)* ppsa);

Indicates which versions of the qbXML specification are supported by the QuickBooks program to which your application is connected in this session. Note that this information might be different from the information returned by a HostQuery request, as described in the Concepts Manual. HostQuery returns the complete list of all qbXML versions supported by the currently open connection, which is usually the information your application will require.
Parameters

ppsa

Array of qbXML version numbers that the QuickBooks Request Processor supports. For example, the array contains 1.0, 1.1, 2.0, 2.1, 3.0 and 4.0 if your application is using the Request Processor from QuickBooks 2004 (U.S. edition). It contains CA2.0 if your application is using the Request Processor from the 2003 Canadian edition of QuickBooks.

Usage

Your application is responsible for freeing the memory used for the ppsa array. For example, to release the memory for the array when using the C++ language, call SafeArrayDestroy(ppsa). For sample code and a description of how to use QBXMLVersionsForSession, see Checking the QuickBooks Version in Chapter 8 of the Concepts Manual. When QBXMLVersionsForSession is called on QBOESessionManager, it returns NULL and a status of S_OK.

42 Chapter 2: Communicating with QuickBooks


(c) 2004 Intuit Inc. All rights reserved.

QBXMLVersionsForSubscription
HRESULT QBXMLVersionsForSubscription([out, retval] SAFEARRAY (BSTR)** ppsa);

Returns an array containing a list of qbXML versions that are available for subscription requests.
Parameters

ppsa

Pointer pointer to an array of binary strings that specify the versions of the qbXML specifications that support the SDK event subscription feature. Currently the possible values are 3.0 and 4.0.

Usage

Your application is responsible for freeing the memory used for the ppsa array. For example, to release the memory for the array when using the C++ language, call SafeArrayDestroy(ppsa). When QBXMLVersionsForSubscription is called on QBOESessionManager, it returns NULL and a status of S_OK.

CreateSubscriptionMsgSetRequest
HRESULT CreateSubscriptionMsgSetRequest( short qbXMLMajorVersion, short qbXMLMinorVersion, [out, retval] ISubscriptionMsgSetRequest** request);

Creates and returns an interface pointer to ISubscriptionMsgSetRequest. For more information about QBFC event recovery, see Event Notification on page 54.
Parameters

qbXMLMajorVersion The major version of qbXML to be used by your application. (For example, if the version is 4.0, the major version is 4.) qbXMLMinorVersion The minor version of qbXML to be used by your application. (For example, if the version is 4.0, the minor version is 0.) request The request message set object, to which you will add one or more subscription request messages.

When CreateSubscriptionMsgSetRequest is called on QBOESessionManager, it returns NULL and a status of S_OK.

Functions of QBSessionManager 43
(c) 2004 Intuit Inc. All rights reserved.

DoSubscriptionRequestsFromXMLString
HRESULT DoSubscriptionRequestsFromXMLString( BSTR qbXMLSubscriptionRequest, [out, retval] ISubscriptionMsgSetResponse** responseSet);

Sends an XML request as a string rather than in an ISubscriptionMsgSetRequest object (as happens in DoSubscriptionRequests). For more information about QBFC event recovery, see Event Notification on page 54.
Parameters

qbXMLSubscriptionRequest Contains the subscription XML request. The request is not validated before it is sent. responseSet A parsed list of responses, one for every request in the request message set.

When DoSubscriptionRequestsFromXMLString is called on QBOESessionManager, it returns NULL and a status of S_OK.

ToSubscriptionMsgSetResponse
HRESULT ToSubscriptionMsgSetResponse( BSTR qbXMLSubscriptionResponse, short qbXMLMajorVersion, short qbXMLMinorVersion, [out, retval] ISubscriptionMsgSetResponse** responseSet);

Parses the XML response and returns it in an ISubscriptionMsgSetResponse object. For more information about QBFC event recovery, see Event Notification on page 54.
IMPORTANT This method performs no version or qbXML validation. You are responsible for supplying a valid qbXML string.
Parameters

qbXMLSubscriptionResponse The qbXML response document (as a string) that gets returned from QuickBooks after processing a subscription request message. qbXMLMajorVersion The major version of qbXML to be used for this operation. (For example, if the version is 4.0, the major version is 4.) qbXMLMinorVersion The minor version of qbXML to be used for this operation. (For example, if the version is 4.0, the minor version is 0.) responseSet The response message set object, which will contain a list of responses, one for every request in the request message set.

44 Chapter 2: Communicating with QuickBooks


(c) 2004 Intuit Inc. All rights reserved.

When ToSubscriptionMsgSetResponse is called on QBOESessionManager, it returns NULL and a status of S_OK.

DoSubscriptionRequests
HRESULT DoSubscriptionRequests( ISubscriptionMsgSetRequest* request, [out, retval] ISubscriptionMsgSetResponse** responseSet);

Sends the subscription request to the request processor and returns a response. For more information about QBFC event recovery, see Event Notification on page 54.
Parameters

request responseSet
Usage

The request message set object containing any number of subscription requests to be processed by QuickBooks. The parsed response message set object, which will contain a list of responses, one for every subscription request in the message set.

Before sending the request set to QuickBooks for processing, this method verifies the given request message set to make sure that all the mandatory fields in each of its requests have been set and that no two mutually exclusive fields have been set. When DoSubscriptionRequests is called on QBOESessionManager, it returns NULL and a status of S_OK.

ToEventsMsgSet
HRESULT ToEventsMsgSet( BSTR qbXMLEventsResponse, short qbXMLMajorVersion, short qbXMLMinorVersion, [out, retval] IEventsMsgSet** responseSet);

Parses the XML response and returns it in an IEventMsgSetResponse object. For more information about QBFC event recovery, see Event Notification on page 54.
IMPORTANT This method performs no version or qbXML validation. You are responsible for supplying a valid qbXML string.
Parameters

qbXMLEventsResponse The qbXML response document (as a string) sent from QuickBooks after a subscribed event occurs.

Functions of QBSessionManager 45
(c) 2004 Intuit Inc. All rights reserved.

qbXMLMajorVersion The major version of qbXML to be used for this operation. (For example, if the version is 4.0, the major version is 4.) qbXMLMinorVersion The minor version of qbXML to be used for this operation. (For example, if the version is 4.0, the minor version is 0.) responseSet The response message set object, which will contain a list of responses, one for every request in the request message set.

When ToEventsMsgSet is called on QBOESessionManager, it returns NULL and a status of S_OK.

CommunicateOutOfProcess
HRESULT CommunicateOutOfProcess(VARIANT_BOOL useOutOfProc) Parameters

useOutOfProc

Specify True to communicate with QuickBooks out-of-process, or False for in-process communication.

This call is useful when your application must run as part of a windows service process and therefore does not have permission to communicate with QuickBooks in-process (the normal type of QuickBooks communication. You call this method prior to calling OpenConnection2 so the SDK knows which request processor to use (qbXMLRP2e, in this case).
IMPORTANT In order for this call to work, you must install and register (in the Windows registry) the redistributable program QBXMLRP2e.exe. This is located in the SDK install subdirectory \tools\access\QBXMLRP2e

If you attempt to call this method when you currently have a connection open, the error HRESULT 0x80040313 is returned from the QBSessionManager: "The mode of communication has already been established, and once set, it cannot be changed. " If you invoke this method with the parameter set to True, and then attempt to open a connection using the QBOESessionManager, the status returned is s_ok, but nothing happens and you cannot communicate with QuickBooks. If this method is invoked and there is some problem creating the COM component required for out-of-process communication, the error HRESULT 0x80040314 is returned from the QBSessionManager: "Cannot create QBXMLRP2e COM component."

ConnectionType
HRESULT ConnectionType([out, retval] QBXMLRPConnectionType* pVal);

46 Chapter 2: Communicating with QuickBooks


(c) 2004 Intuit Inc. All rights reserved.

Parameters

ConnectionType

Pointer to the returned connection type indicating the currently opened connection. The type returned will be one of the following values: ctUnknown, ctLocalQBD, ctRemoteQBD, ctLocalQBDLaunchUI, or ctRemoteQBOE.

The type returned will be one of the following values that reflect the way the connection was first opened: ctLocalQBD (local QuickBooks) ctRemoteQBD (RDS connection) ctLocalQBDLaunchUI (SDK application launched QuickBooks in interactive mode) ctRemoteQBOE (QBOE connection opened via OpenConnection2 call) ctUnknown (QBOE connection opened via QBOESessionManager),

QBAuthPreferences
For more information on this property of the QBSessionManager, see Functions of QBAuthPreferences.

Functions of QBAuthPreferences
The QBAuthPreferences method is invoked on the QBSessionManager to return the session managers authorization property object, IAuthPreferences. This is used to cause QuickBooks to display the proper authorization dialogs, as described previously under Enabling Users to Authorize Your Application. The IAuthPreferences object has the following methods: GetIsReadOnly. Determines whether your application has specified that it is read-only. PutIsReadOnly. Specifies whether your application is read-only. GetUnattendedModePref. Determines whether your application has specified that it requires unattended mode. PutUnattendedModePref. Specifies whether your application requires unattended mode. GetPersonalDataPref. Determines whether your application has specified that it requires access to personal data. PutPersonalDataPref. Specifies whether your application requires access to personal data. WasAuthPreferencesObeyed. Determines whether the QBAuthPreferences property and methods are supported by the QuickBooks currently running

All of these are described in the following pages.

Functions of QBAuthPreferences 47
(c) 2004 Intuit Inc. All rights reserved.

QBAuthPreferences
HRESULT QBAuthPreferences([out, retva] IQBAuthPreferences** ppAuthPreferences)

Returns the IQBAuthPreferences object to be used to set or get authorization preferences.


Parameters **ppAuthPreferences

Pointer pointer to the returned preferences object. For more information on the use of this, see Using QBAuthPreferences to Obtain Proper Application Authorization (page 23). You cannot call this on remote connections, such as via RDS or QBOE. An error (0x8004042A) results if you attempt it.

GetIsReadOnly
HRESULT GetIsReadOnly(VARIANT_BOOL *pIsReadOnly)

Returns the applications read-only access requirements from the IQBAuthPreferences object.
Parameters

**pIsReadOnly

Pointer to the returned read-only preferences.

For more information on the use of this, see Using QBAuthPreferences to Obtain Proper Application Authorization (page 23).

PutIsReadOnly
HRESULT PutIsReadOnly(VARIANT_BOOL isReadOnly)

Invoked on the IQBAuthPreferences object to specify whether your application needs readonly access to the company file.
Parameters isReadOnly

Specify True if your application accesses QuickBooks only in read mode. Specify False if your application needs to write data to QuickBooks.

If your application specifies True, then the user must authorize read-only access (and whatever other preferences are currently specified in the IQBAuthPreferences object). If your application subsequently attempts to write data to QuickBooks, it will not be allowed to write and an error will be returned in the responses that attempts to write data.

48 Chapter 2: Communicating with QuickBooks


(c) 2004 Intuit Inc. All rights reserved.

For more information on the use of this, see Using QBAuthPreferences to Obtain Proper Application Authorization (page 23).

GetUnattendedModePref
HRESULT GetUnattendedModePref(ENUnattendedModePrefType *pUnattendedModePref)

Returns the applications unattended mode requirements from the IQBAuthPreferences object.
Parameters *pUnattendedModePref

Pointer to the returned setting, which will be either umptRequired or umptOptional. For more information on the use of this, see Using QBAuthPreferences to Obtain Proper Application Authorization (page 23)

PutUnattendedModePref
HRESULT PutUnattendedModePref(ENUnattendedModePrefType UnattendedModePref)

Invoked on the QBAuthPreferences object to specify whether your application needs unattended mode (auto-login) access to the company file.
Parameters UnattendedModePref

Specify umptRequired or umptOptional. Specify umptRequired if your application must be able to run in unattended mode or umptOptional if such access is not required. For more information on the use of this, see Using QBAuthPreferences to Obtain Proper Application Authorization (page 23).

GetPersonalDataPref
HRESULT GetPersonalDataPref(ENPersonalDataPrefType *pPersonalDataPref)

Returns the applications personal data access requirements from the IQBAuthPreferences object.

Functions of QBAuthPreferences 49
(c) 2004 Intuit Inc. All rights reserved.

Parameters pPersonalDataPref

Pointer to the returned preferences setting. Returns pdptRequired, pdptOptional, or pdptNotNeeded. A value of pdptRequired means that your application will not run unless the administrative user grants access to personal data. A value of pdptOptional means that the application may use personal data, but can still run if the user does not grant it that access. A value of pdptNotNeeded means that your application does not use personal data and the user will not have the opportunity to grant it that access. If your application attempts to access personal data, any personal data will be automatically filtered out and will not appear in the responses to requests. For more information on the use of this, see Using QBAuthPreferences to Obtain Proper Application Authorization (page 23).

PutPersonalDataPref
HRESULT PutPersonalDataPref(ENPersonalDataPrefType personalDataPref)

Invoked on the QBAuthPreferences object to specify your applications requirements regarding access to personal data in the company file.
Parameters personalDataPref

Specify pdptRequired, pdptOptional, or pdptNotNeeded. A value of pdptRequired means that your application will not run unless the administrative user grants access to personal data. A value of pdptOptional means that the application may use personal data, but can still run if the user does not grant it that access. A value of pdptNotNeeded means that your application does not use personal data and the user will not have the opportunity to grant it that access. If your application attempts to access personal data, any personal data will be automatically filtered out and will not appear in the responses to requests. For more information on the use of this, see Using QBAuthPreferences to Obtain Proper Application Authorization (page 23).

WasAuthPreferencesObeyed
HRESULT WasAuthPreferencesObeyed(VARIANT_BOOL *pWasAuthPreferencesObeyed)

Returns verification whether the current version of QuickBooks supports the IQBAuthPreferences object property and methods.

50 Chapter 2: Communicating with QuickBooks


(c) 2004 Intuit Inc. All rights reserved.

Parameters pWasAuthPreferencesObeyed

Pointer to the returned value. True means there is support for IQBAuthPreferences, False means there is no support. This method is useful for determining whether the QuickBooks currently being accessed is capable of supporting the authorization preferences feature. For more information on the use of this, see Using QBAuthPreferences to Obtain Proper Application Authorization (page 23).

Functions of QBOESessionManager
The properties shown below (along with those listed in Functions of QBSessionManager and QBOESessionManager) are used for communication with QuickBooks Online Edition.
TIP For more details about how these properties are used, see the Developers Guide for QuickBooks Online Edition and the BillAdd sample (written in VB), located in the \samples\qbdt\vb\qbfc\billadd folder.

ApplicationLogin
HRESULT ApplicationLogin([out, retval] IQBStringType* *pVal);

The application name that you supplied when you registered to obtain an application ID.

ConnectionTicket
HRESULT ConnectionTicket([out, retval] IQBStringType* *pVal);

The ticket copied by the user into your application as a result of the application authorization process.

InstallationID
HRESULT InstallationID([out, retval] IQBIDType* *pVal);

Used for error recovery. We recommend that you create a unique installation ID for each instance of your desktop application.

Functions of QBOESessionManager 51
(c) 2004 Intuit Inc. All rights reserved.

Language
HRESULT Language([out, retval] IQBStringType* *pVal);

The language used by QuickBooks Online Edition. The default is English.

AppID
HRESULT AppID([out, retval] IQBStringType* *pVal);

The application ID assigned when you registered your application with Intuit Developer Network.

AppVer
HRESULT AppVer([out, retval] IQBStringType* *pVal);

The version of your application.

SessionTicket
HRESULT SessionTicket([out, retval] IQBStringType* *pVal);

If the initial post connection ticket represents authorization without session authentication, the session ticket is returned in the sign-on response. If the connection ticket was created with session authentication, however, no session ticket is returned and the error Session Authentication Required is returned.

AuthID
HRESULT AuthID([out, retval] IQBIDType* *pVal);

The AuthID is optional in a sign-on message request.

52 Chapter 2: Communicating with QuickBooks


(c) 2004 Intuit Inc. All rights reserved.

Automated Error Recovery


This section assumes that you are familiar with the information on error recovery in Chapter 8, Making Your Application Robust, in the Concepts Manual. QBFC4 extends the existing SDK error-recovery mechanism by automating the creation and addition of the new MessageSetID and oldMessageSetID, and by saving the request message set to disk (if SaveAllMsgSetRequestInfo is set to true). This enables your application to determine which request corresponds to the response status that the errorrecovery feature returns. For QuickBooks, QBFC error-recovery information is unique to a given integrated application (GUID specified by ErrorRecoveryID) and company file. As a result, a session must be started before certain QBFC error-recovery functions can be executed. (Only EnableErrorRecovery, ErrorRecoveryID, and SaveAllMsgSetRequestInfo can be executed before a session is started.) For QuickBooks Online Edition, QBFC error-recovery information is unique to a given integrated application (GUID specified by error recovery ID) and a connection ticket. As a result, the connection-ticket value must be known before IsErrorRecoveryInfo, ClearErrorRecoveryInfo, GetErrorRecoveryStatus, and GetSavedMsgSetRequest are called. The QBSessionManager and QBOESessionManager interfaces have the following new methods that support automated error recovery: IsErrorRecoveryInfo (page 36) ClearErrorRecovery (page 37) EnableErrorRecovery (page 37) ErrorRecoveryID (page 37) SaveAllMsgSetRequestInfo (page 37) GetErrorRecoveryStatus (page 38) GetSavedMsgSetRequest (page 38)

NOTE QBFC automated error recovery is available only for data message sets (not for subscription and event messages).
Steps for Automated Error Recovery

In general, these are the steps you need to follow to use QBFCs automated error recovery in your application: 1. Set the error recovery ID, using the ErrorRecoveryID function. 2. Set EnableErrorRecovery to true to enable error recovery. 3. Set SaveAllMsgSetRequestInfo to true so the entire contents of the MsgSetRequest will be saved to disk. If Save All MsgSetRequestInfo is false (the default), only the NewMessageSetID will be saved.

Automated Error Recovery 53


(c) 2004 Intuit Inc. All rights reserved.

4. Use IsErrorRecoveryInfo to check whether an unprocessed response exists. If IsErrorRecoveryInfo is true: a. b. c. d. Get the response status, using GetErrorRecoveryStatus. Get the saved request, using GetSavedMsgSetRequest. Process the response, possibly using the saved request. Clear the response status, using ClearErrorRecovery.

5. Send the current request set. 6. Process the response from the current request. 7. Clear the response status, using ClearErrorRecovery.
Error Recovery and Query Requests

Generally, error recovery is not used with query requests. If your application does not receive a response from a query request, you would usually just resubmit the query. We recommend that your application disable error recovery before querying, and then re-enable it before starting other requests.

Event Notification
QBFC supports event notification. This section gives information about QBFC-specific aspects of event notification. For general information about the SDK event-notification mechanism and details about how it interacts with QuickBooks, see Chapter 5, Event Notification, in the Concepts Manual. The QBFCEventsSubscriber and QBFCEventsCallback samples, located in the \samples\qbdt\vb\qbfc folder, work together to show how to implement data event subscription and callback handling using the QBFC library. In the Onscreen Reference, subscription and event-callback messages are listed separately from the data messages.
NOTE Event-notification is not currently supported for QuickBooks Online Edition.

Subscription
IMPORTANT See the Concepts manual chapter on Event Notification for information regarding the effect of SDK versioning on subscriptions.

Event notification requires subscription. QBFC has two high-level objects that are used for subscription request and response message sets: ISubscriptionMsgSetRequest (page 65)

54 Chapter 2: Communicating with QuickBooks


(c) 2004 Intuit Inc. All rights reserved.

ISubscriptionMsgSetResponse (page 72)

Seven request objects and their corresponding response objects use the high-level subscription objects: DataEventSubscriptionAdd (shown in Listing 2-1, below) is used to subscribe to receive notification when certain QuickBooks transaction events and/or list events occur. DataEventSubscriptionQuery is used to query to receive information about a data-event subscription that is set up. UIEventSubscriptionAdd is used to subscribe to receive notification when certain events happen in the QuickBooks UI. UIEventSubscriptionQuery is used to query to receive information about a UI-event subscription that is set up. UIExtensionSubscriptionAdd is used to subscribe to receive notification when your UI extensions generate events within QuickBooks (for example, when an end-user selects a menu extension that you have added to QuickBooks). UIExtensionSubscriptionQuery is used to query to receive information about a UIextension subscription that is set up. SubscriptionDel is used to delete a subscription.

The QBSessionManager interface has five new methods that support subscription: CreateSubscriptionMsgSetRequest (page 43) DoSubscriptionRequestsFromXMLString (page 44) ToSubscriptionMsgSetResponse (page 44) DoSubscriptionRequests (page 45) ToEventsMsgSet (page 45)

Example: Subscribing to Data Events Listing 2-1 shows a segment of C++ code that uses QBFC to add a subscription request. The request specifies that the callback application (identified by its CLSID) should be notified when an account or a customer is added, modified, or deleted in QuickBooks.
_______ Listing 2-1 Subscribing to data events (C++ example) IQBSessionManagerPtr sessionManager(CLSID_QBSessionManager); //create subscription message set ISubscriptionMsgSetRequestPtr subRequestMsgSet = sessionManager->CreateSubscriptionMsgSetRequest(4, 0);

Event Notification 55
(c) 2004 Intuit Inc. All rights reserved.

//add data event subscription IDataEventSubscriptionAddPtr dateEventSubAdd = subRequestMsgSet->AppendDataEventSubscriptionAddRq(); dateEventSubAdd ->COMCallbackInfo->CLSID->SetValue(myClsID); dateEventSubAdd ->TrackLostEvents->SetValue(tleAll); dateEventSubAdd ->DeliverOwnEvents->SetValue(False); //add data list events IListEventSubscriptionPtr listEventSub = dateEventSubAdd ->ListEventSubscriptionList->Append(); listEventSub ->ListEventTypeList->Add(letAccount); listEventSub ->ListEventTypeList->Add(letCustomer); listEventSub ->ListEventOperationList->Add(leoAdd); listEventSub ->ListEventOperationList->Add(leoModify); listEventSub ->ListEventOperationList->Add(leoDelete); //open connection sessionManager->OpenConnection2 ( APPID, APPNAME, ctLocalQBD); //send request ISubscriptionMsgSetResponsePtr queryResponse = sessionManager->DoSubscriptionRequests(subRequestMsgSet);

Callback
When a subscribed event occurs, your applications callback method receives an event XML string that you must load into an IEventsMsgSet object using the ToEventsMsgSet method as shown in the following snippet:
Dim eventMsgSet As IEventsMsgSet Dim sessionManager As New QBSessionManager Set eventMsgSet = sessionManager.ToEventsMsgSet(eventXML, 4, 0)

From the event string supplied to your callback, and loaded into IEventsMsgSet as shown in the snippet above, IEventsMsgSet can contain one of three possible types of event objects, based on the type of event that occurred: DataEventList object, a UIEvent object, or a UIExtensionEvent object. The QBSessionManager interface has one new method that supports event callback: ToEventsMsgSet (page 45)

It is possible to recover from lost data events, but not from lost UI events or UI extension events. For more information, see the next section, Event Recovery. Listing 2-2 shows a C++ example of how your application might process a callback that corresponds to the subscription added in Listing 2-1.

56 Chapter 2: Communicating with QuickBooks


(c) 2004 Intuit Inc. All rights reserved.

Example: Processing an Event Callback


_______ Listing 2-2 Processing event callback information using QBFC (C++ example) STDMETHODIMP CallBackClass::inform(BSTR eventXML) { IQBSessionManagerPtr sessionManager(CLSID_QBSessionManager); //Create the EventsMessageSet from XML IEventsMsgSetPtr eventMsgSet = sessionManager->ToEventsMsgSet(eventXML, 4, 0); //Iterate through the Data Events if(eventMsgSet->IOREvent->DataEventList != NULL){ long numDataEvents = eventMsgSet->OREvent->DataEventList->Count; for (int i = 0; i< numDataEvents; i++){ IDataEventPtr dataEvent = eventMsgSet->OREvent->DataEventList->GetAt(i); DATE lastRestoreTime = dataEvent->GetLastRestoreTime()->GetValue(); DATE lastCondenseTime = dataEvent->GetLastCondenseTime()->GetValue(); DATE recoveryTime = dataEvent->GetDataEventRecoveryTime()->GetValue(); bstr_t companyFile = dataEvent->GetCompanyFilePath()->GetValue(); //Iterate through Data List Events if(dataEvent->GetORListTxnEvent()->GetListEvent() != NULL){ IListEventPtr listEvent = dataEvent->GetORListTxnEvent()->GetListEvent(); bstr_t listEventType = listEvent->GetListEventType()->GetAsString(); bstr_t listEventOp = listEvent->GetListEventOperation()->GetValue(); bstr_t listID = listEvent->GetListID()->GetValue(); bstr_t afterMerge = listEvent->GetAfterMergeListID()->GetValue(); } } } }

Event Recovery
NOTE DataEventRecoveryInfoQuery and DataEventRecoveryDel requests use the regular QBFC message sets, not the ISubscriptionMsgSetRequest and -Response message sets.

It is possible to recover lost data events, but not lost UI events or UI-extension events. To use QBFC event recovery for data events: 1. When you add a subscription, set TrackLostEvents to tleAll so that QuickBooks will record DataEventRecoveryTime when the first data event is lost. 2. Later, you can check in either of two ways whether any data events have been lost and need to be recovered: You can examine the event callback to see whether

Event Notification 57
(c) 2004 Intuit Inc. All rights reserved.

DataEventRecoveryTime is present for any data events, or you can send a DataEventRecoveryInfoQuery request. Your application can recover from lost data events by querying for data that has changed since the time it started losing data events. To do this, query using DataEventRecoveryTime as the FromModifiedDate and FromDeletedDate. 3. After recovering from lost data events, your application needs to clear the DataEventRecoveryTime so that QuickBooks will mark it again the next time an event is lost for your application. You can do this using a DataEventRecoveryInfoDel request.

58 Chapter 2: Communicating with QuickBooks


(c) 2004 Intuit Inc. All rights reserved.

CHAPTER 3 HIGH-LEVEL REQUEST OBJECTS

1 1

This chapter describes the objects in the QBFC Library that pertain to request information, excluding the actual message content: IMsgSetRequest IAttributesRqSet ISubscriptionMsgSetRequest

IMsgSetRequest
The IMsgSetRequest object has two main functions: It stores the attributes for the request set. It adds and maintains all the requests you want QuickBooks to process.

The IMsgSetRequest object has the following methods and properties: Attributes (page 59) ClearRequests (page 60) RequestList (page 60) ToXMLString (page 60) Verify (page 60) Append methods, which add requests to request message sets. Each request defined in qbXML has a corresponding Append method in QBFC. The Append methods are very similar to each other, so they are described together. See How to Append Requests to the Request Message (page 61).

Attributes
HRESULT Attributes ([out, retval] IAttributesRqSet** pVal)

Use this property to set the onError, oldMessageSetID, newMessageSetID, and responseData attributes. The onError attribute must be set before calling the session managers DoRequests method. For information about each attribute, see IAttributesRqSet (page 63).

IMsgSetRequest 59
(c) 2004 Intuit Inc. All rights reserved.

ClearRequests
HRESULT ClearRequests ()

Clears all requests from this request message set and all the attribute values from the message sets AttributesRqSet object. Call this method only when you want to build a new request set that doesnt contain all the requests and attributes that are in the current one.

RequestList
HRESULT RequestList([out, retval] IRequestList** pVal)

You invoke this on the parent message set to get the IRequestList object you need to perform a count (using its Count method) or retrieve a request from the message set (using its GetAt method).

ToXMLString
HRESULT ToXMLString ([out, retval] BSTR* qbXMLRequest)

Returns the qbXML request document that could be built from this request set. This method is meant to help you debug during code development, and you can use it for error recovery (if your application stores the qbXMLRequest string and then re-sends it to QuickBooks).
NOTE If the IMsgSetRequest object was created from the QBOESessionManager object, qbXMLRequest will include the QuickBooks Online Edition signon request messages. For more information about these messages, see Chapter 4 of the Developers Guide for QuickBooks Online Edition.

Verify
HRESULT Verify ([out] BSTR* detailMsg, [out, retval] VARIANT_BOOL* isOK)

Verifies the internal state of the requests in this request set. If any request has a required field that isnt set, or two mutually exclusive fields that are set, then that request is considered invalid. Keep in mind that the request set will be verified automatically when you invoke the DoRequests method, before being forwarded to QuickBooks.

60 Chapter 3: High-Level Request Objects


(c) 2004 Intuit Inc. All rights reserved.

Parameters

detailMsg

The message containing a description of each case that failed the verification test. If all the requests in the request set are verified to be valid, detailMsg will be an empty string. Returns True in VB and VARIANT_TRUE in C++ (the numeric representation of both is -1) if all the requests in the request set are verified to be valid, and False in VB and VARIANT_FALSE in C++ (the numeric representation of both is 0) otherwise.

isOK

How to Append Requests to the Request Message


The remaining methods of IMsgSetRequest add the requests to the request message set. The name of each of these methods is Append, followed by the name of the underlying qbXML request. Each qbXML request has a corresponding Append method in QBFC. For example, the AppendCustomerAddRq method (QBFC) corresponds to the CustomerAddRq request (qbXML). AppendCustomerAddRq adds an empty CustomerAddRq request to the request set and returns the ICustomerAdd object that must then be filled with any required customer data before you call DoRequests. When using Append methods, remember the following points: You call the Append method to create an empty request object and set it into the IMsgSetRequest object. You must then fill that object with any required data. For example, the sample program shown in Listing 1-1 (page 6) calls AppendCustomerAddRq and then fills the returned ICustomerAdd object with customer name and type data. The request you append must be supported by the version of the SDK installed on each end-users computer. It must also be supported in the version of qbXML you specified in your call to CreateMsgSetRequest and by the country edition of QuickBooks with which your application is interacting. (For example, AppendCurrencyAddRq will not have any effect in a U.S. edition of QuickBooks.) You must set at least all the required fields in every request object before you call DoRequests. To determine which fields are required for any request object, you can use the Onscreen Reference.

Example: AppendCustomerAddRq
HRESULT AppendCustomerAddRq ([out, retval] ICustomerAdd** val)

Adds a CustomerAddRq request to the request message set. You fill the returned ICustomerAdd object with the data needed for this request, including its only required field, Name, before calling the session managers DoRequests method.

IMsgSetRequest 61
(c) 2004 Intuit Inc. All rights reserved.

Parameters

val

The type of each object returned from the Append methods indicates both the type of data in the request as well as the operation requested. In this example, Customer is the type of data in the request, and Add is the operation. Several dozen types of data are used in QuickBooks, including many types of lists, such as customer and account lists, and many types of transactions, such as invoice and purchase order transactions. However, only five types of request operations are used: Add, Mod (for Modify), Query, Del (for Delete), and Void. For more information, see Chapter 5, Message Data Objects.

HRESULT Error Codes

An error code of 0x8004030B will be returned if an Append request is not supported in the version of qbXML you specified in your call to the session managers CreateMsgSetRequest. While you cannot currently get this HRESULT for AppendCustomerAddRq, in general, you will get the 0x8004030B HRESULT if you attempt to append a request that requires a higher SDK level than the level you specified in CreateMsgSetRequest. For example, you would get that error if you attempt to append a 4.0 request but you specify version 2.0 in the call to CreateMsgSetRequest.

IRequestList
The IRequestList object is returned by invoking RequestList on the parent message set object. It has one property (Count) and one method (GetAt) to enable your application to retrieve the requests contained in the list.

Count
HRESULT Count([out, retval] long *pVal);

Returns the number of requests in the request list.


Parameters

pVal

Pointer to the returned count of

GetAt
HRESULT GetAt(long index, [out,retval] IRequest** retVal);

Returns from the request list the request located at the given index.

62 Chapter 3: High-Level Request Objects


(c) 2004 Intuit Inc. All rights reserved.

IRequest
IRequest has the following three functions.

RequestID
HRESULT RequestID([out, retval] long *pVal);

Detail
HRESULT Detail([out, retval] IQBBase** pVal);

Type
HRESULT Type([out, retval] IRequestType** pVal);

IAttributesRqSet
The IAttributesRqSet object is returned by the Attributes property. IAttributesRqSet consists of four properties, which correspond to the possible attributes in the request message set: OnError (page 63) OldMessageSetID (page 64) NewMessageSetID (page 64) ResponseData (page 65)

OnError
HRESULT OnError ([in] ENRqOnError pVal) HRESULT OnError ([out, retval] ENRqOnError* pVal)

The OnError property is required. You must set it before calling the session managers DoRequests method.
Parameters

pVal

An enum that indicates whether or not you want QuickBooks to continue processing requests in the request set if an error with one of them is encountered.

IRequest 63
(c) 2004 Intuit Inc. All rights reserved.

In the current SDK, pVal has two valid values:


roeStop means no more requests will be processed once an error with one of them is

encountered.
roeContinue means all the requests will be processed, even if one or more of them

produce an error.
roeRollback is not supported in the current version of the SDK.
HRESULT Error Codes

An error code of 0x80040300 will be returned if OnError is retrieved before it has been set. An error code of 0x80040302 will be returned if you try to set OnError to a value that is not defined by qbXML.

OldMessageSetID
HRESULT OldMessageSetID ([in] BSTR val) HRESULT OldMessageSetID ([out, retval] BSTR* val)

OldMessageSetID is optional. The SDK error recovery mechanism uses it in several ways, depending on the value of NewMessageSetID. Usually, OldMessageSetID represents the unique identifier of the previous request message set, as defined by the application. For more information, see Error Recovery in Chapter 8 of the Concepts Manual.
Parameters

val

If val is set to an empty string (), no OldMessageSetID attribute is sent to QuickBooks.

NewMessageSetID
HRESULT NewMessageSetID ([in] BSTR val) HRESULT NewMessageSetID ([out, retval] BSTR* val)

NewMessageSetID is optional. The SDK error recovery mechanism uses it in several ways, depending on the value of OldMessageSetID. Usually, NewMessageSetID represents the unique identifier for this request message set, as defined by the application. For more information, see Error Recovery in Chapter 8 of the Concepts Manual.
Parameters

val

If val is set to an empty string (), no NewMessageSetID attribute is sent to QuickBooks.

64 Chapter 3: High-Level Request Objects


(c) 2004 Intuit Inc. All rights reserved.

ResponseData
HRESULT ResponseData ([in ENRqResponseData Val) HRESULT ResonseData ([out, retval] ENRqResponseData* val)

Indicates how much information to return in the response.


Parameters

val

val has two possible values: rdIncludeAll, which returns the normal response, or rdIncludeNone, which returns status information but no data.

ISubscriptionMsgSetRequest
The ISubscriptionMsgSetRequest object is returned by the QBSessionManagers CreateSubscriptionMsgSetRequest property. ISubscriptionMsgSetRequest is used by the subscription request message objects: DataEventSubscriptionAdd DataEventSubscriptionQuery UIEventSubscriptionAdd UIEventSubscriptionQuery UIExtensionSubscriptionAdd UIExtensionSubscriptionQuery SubscriptionDel

For more details, see Event Notification on page 54. ISubscriptionMsgSetRequest consists of the following methods.

ClearRequests
HRESULT ClearRequests();

ToXMLString
HRESULT ToXMLString([out, retval] BSTR* qbXMLSubscriptionRequest);

Verify
HRESULT Verify([out] BSTR* errorMsg, [out, retval] VARIANT_BOOL* isOK);

ISubscriptionMsgSetRequest 65
(c) 2004 Intuit Inc. All rights reserved.

AppendUIEventSubscriptionQueryRq
HRESULT AppendUIEventSubscriptionQueryRq( [out, retval] IUIEventSubscriptionQuery** val);

AppendUIExtensionSubscriptionQueryRq
HRESULT AppendUIExtensionSubscriptionQueryRq( [out, retval] IUIExtensionSubscriptionQuery** val);

AppendDataEventSubscriptionQueryRq
HRESULT AppendDataEventSubscriptionQueryRq( [out, retval] IDataEventSubscriptionQuery** val);

AppendUIExtensionSubscriptionAddRq
HRESULT AppendUIExtensionSubscriptionAddRq( [out, retval] IUIExtensionSubscriptionAdd** val);

AppendUIEventSubscriptionAddRq
HRESULT AppendUIEventSubscriptionAddRq( [out, retval] IUIEventSubscriptionAdd** val);

AppendDataEventSubscriptionAddRq
HRESULT AppendDataEventSubscriptionAddRq( [out, retval] IDataEventSubscriptionAdd** val);

AppendSubscriptionDelRq
HRESULT AppendSubscriptionDelRq([out, retval] ISubscriptionDel** val);

66 Chapter 3: High-Level Request Objects


(c) 2004 Intuit Inc. All rights reserved.

CHAPTER 4 HIGH-LEVEL RESPONSE OBJECTS

1 1

This chapter describes the objects in the QBFC Library that pertain to response information, excluding the actual message content: IMsgSetResponse IResponseList IResponse IAttributesRsSet ISubscriptionMsgSetResponse

Objects that correspond to the actual message content are described in Chapter 5, Message Data Objects.

IMsgSetResponse
The IMsgSetResponse object is returned by DoRequests (page 34), except when DoRequests fails. IMsgSetResponse contains the responses and attributes as defined in the underlying qbXML. The responses are maintained in the form of a list, which contains one response for every request in the request set that was passed to DoRequests. Each of these responses holds status information, and possibly data, returned from QuickBooks.

ResponseList
HRESULT ResponseList ([out, retval] IResponseList** pVal)

Returns the list of responses contained in the response message set. For related information, see IResponseList (page 68).

Attributes
HRESULT Attributes ([out, retval] IAttributesRsSet** pVal)

Returns the attributes for the response message set. If neither of the properties in Attributes is set, then this will be NULL (Nothing in VB). For related information, see IAttributesRsSet (page 71).

IMsgSetResponse 67
(c) 2004 Intuit Inc. All rights reserved.

ToXMLString
HRESULT ToXMLString ([out, retval] BSTR* qbXMLResponse)

Returns (as a string) the qbXML response document that could be built from this response message set. Its primary purpose is to help with debugging during code development. The return will be an empty string if DoRequests has not been called.
NOTE If the IMsgSetResponse object was created from the QBOESessionManager object, qbXMLResponse will include the QuickBooks Online Edition signon response messages. For more information about signon messages, see Chapter 4 of the Developers Guide for QuickBooks Online Edition.

IResponseList
The IResponseList object is a property within the IMsgSetResponse object that gets returned from the session managers DoRequests method. It contains the list of responses from QuickBooks to the requests contained in the request message set. Each request sent in the call to DoRequests has a corresponding response, and the responses are contained in a list even if there is only one of them. For an example, see 4. Check response status and data (page 11). The responses will be returned in the same order as the requests were added to the request message set. IResponseList has one property (Count) and one method (GetAt) to enable your application to retrieve the responses contained in the list.

Count
HRESULT Count ([out, retval] long* pVal)

Returns the number of responses in the response list.

GetAt
HRESULT GetAt ([in] long index, [out, retval] IResponse** retVal)

Returns from the response list the response located at the given index.
Parameters

index retVal

The zero-based index of the desired response within the response list. The returned response.

68 Chapter 4: High-Level Response Objects


(c) 2004 Intuit Inc. All rights reserved.

For related information, see IResponse (page 69).


HRESULT Error Codes

An error code of 0x80040303 will be returned if the given index is out of range for the response list.

IResponse
The IResponse object corresponds to the response message in the underlying qbXML. It is contained in the IResponseList that is part of the IMsgSetResponse. Its properties represent the status information and the contents of the message, as well as the type of the response.

retCount
HRESULT retCount([out, retval] long* pVal)

If the original query request for this response specified metaData only to be returned, the retCount attribute contains the count of the objects that would be returned from the query. The purpose of this is to determine whether you need to break up the query into smaller pieces using the MaxReturned feature available to most queries, or the IncludeRetElement feature (available to most requests) to limit the data returned in the query. The retCount is a pre-count and should not be expected to match exactly the count when you actually perform the query and get objects back. It is possible for some items to be deleted or added between the time you issue the first query with metaData specified and the second query to get the objects. That is, youll still need to do a count on the second query.

StatusCode
HRESULT StatusCode ([out, retval] long* pVal)

Returns the status code for this response. If the status code is not 0 (zero), your application should check the StatusSeverity and/or StatusMessage for more information.

StatusSeverity
HRESULT StatusSeverity ([out, retval] BSTR* pVal)

Returns the status severity for this response. It can be one of three values: Info, Warn (for Warning), or Error.

IResponse 69
(c) 2004 Intuit Inc. All rights reserved.

StatusMessage
HRESULT StatusMessage ([out, retval] BSTR* pVal)

Returns the status message for this response message, depending on what the status code is: If StatusCode is 0, StatusMessage is Status OK. If StatusCode is not 0, StatusMessage provides a detailed description of what happened.

NOTE For a complete list of status codes, their severities, and their messages, refer to the Onscreen Reference.

Detail
HRESULT Detail ([out, retval] IQBBase** pVal)

Returns the contents of the response message.


Parameters

pVal

If the response contains no data, which can happen if the StatusCode is not 0, or if the includenone attribute is used, or if the metaData attribute in a query is set to mdMetaDataOnly, then Detail will be NULL (Nothing in VB). When Detail doesnt exist, the StatusCode will indicate the reason.

Usage

When the Detail property exists, it corresponds to a Ret object or a list of Ret objects: An Add, Mod, Del, Void, HostQuery, or PreferencesQuery request will return a list containing a single Ret object. To see how to handle a single Ret object, see Sample Program: Adding a Customer (page 5). Query requests (other than HostQuery and PreferencesQuery) will return a list of Ret objects, even if there is only one Ret object in this list. To see how to handle a list of Ret objects, see either the InvoiceQuery or ItemQuery sample program in the \samples\qbdt\cpp or \samples\qbdt\cpp folder. (To download the samples and the rest of the SDK, visit http://developer.intuit.com/QuickBooksSDK/Downloads/.)

The type of Ret object or Ret object list returned depends on the type of data in the request. If the type of request were CustomerAdd, Customer would be the type of data in the request, and Customer would be the type of Ret object in the response. In three cases the type of Ret object depends on, but doesnt match, the type of data in the request: ItemQuery, EntityQuery, and TermsQuery. The ItemQuery sample program shows what to do in these situations.

70 Chapter 4: High-Level Response Objects


(c) 2004 Intuit Inc. All rights reserved.

Any field in a Ret object that is not required (not guaranteed) can be NULL (Nothing in VB). If a field is guaranteed, you can safely access it (with the GetValue method, for example) without first checking that it exists. If a field is not guaranteed, you need to verify that it exists before accessing it like this. To determine which fields are guaranteed for any Ret object, use the Onscreen Reference. However, be aware that if you use IncludeRetElement in your request to limit the data returned in the response, then even the guaranteed data may not be returned. That is, if you specified you dont want data by using IncludeRetElement, then it wont be included in the response. See also: For more information on the objects contained in Detail, see the Onscreen Reference. For more information on Ret objects and the IQBBase object, see Chapter 5, Message Data Objects.

Type
HRESULT Type ([out, retval] IResponseType** pVal)

Returns the specific type of the response. You can get the type as either a string or an enum value. For example, if the response were an ICustomerAddRs object: You could use IResponseTypes GetAsString method to retrieve the responses type as a string, CustomerAddRs, or You could use IResponseTypes GetValue method to retrieve the objects type as an enum value, rtCustomerAddRs. The COM enum type ENResponseType contains rtCustomerAddRs, as well as enum values for every other type of response defined in QBFC.

NOTE Type corresponds to the response itself, not to the responses Detail. For information on the type of the Detail, refer to IQBBase (page 74).

IAttributesRsSet
The IAttributesRsSet object is a property within the IMsgSetResponse object that gets returned from the session managers DoRequests method. It consists of two properties corresponding to the possible attributes in the response message set: NewMessageSetID and MessageSetStatusCode. If neither of these properties is set, then the Attributes property in the IMsgSetResponse object will be NULL (Nothing in VB).

NewMessageSetID
HRESULT NewMessageSetID ([out, retval] BSTR* pVal)

IAttributesRsSet 71
(c) 2004 Intuit Inc. All rights reserved.

Returns a string that matches the unique identifier of the same name in the request message set, as defined by the application. It is returned only when your application uses the error recovery mechanism for the corresponding request message set. For more information, refer to Chapter 8 in the Concepts Manual.

MessageSetStatusCode
HRESULT MessageSetStatusCode ([out, retval] BSTR* pVal)

Returns a string that indicates the error recovery status code for the response message set. It is returned only under certain circumstances when your application uses the error recovery mechanism for the corresponding request message set. For more information, refer to Chapter 8 in the Concepts Manual.

ISubscriptionMsgSetResponse
The ISubscriptionMsgSetResponse object is returned by the QBSessionManager object's DoSubscriptionRequestsFromXMLString, ToSubscriptionMsgSetResponse, and DoSubscriptionRequests properties. ISubscriptionMsgSetResponse is used by the subscription response message objects: DataEventSubscriptionAdd DataEventSubscriptionQuery UIEventSubscriptionAdd UIEventSubscriptionQuery UIExtensionSubscriptionAdd UIExtensionSubscriptionQuery SubscriptionDel

For more details, see Event Notification on page 54. ISubscriptionMsgSetResponse consists of the following property and method.

ResponseList
HRESULT ResponseList([out, retval] IResponseList* *pVal);

ToXMLString
HRESULT ToXMLString([out, retval] BSTR* qbXMLSubscriptionResponse);

72 Chapter 4: High-Level Response Objects


(c) 2004 Intuit Inc. All rights reserved.

CHAPTER 5 MESSAGE DATA OBJECTS

1 1

This chapter describes the objects in the QBFC Library that correspond to the actual content of request and response messages, plus the objects that correspond to subscription requests and callback responses: IQBBase is the QBFC interface from which all message data objects derive. Six types of top-level QBFC objects contain data: Add (page 74), Mod (page 75), Del (page 76), Void (page 77), Ret (page 78), and Query objects (page 79). This chapter describes only how these six objects are named and used in QBFC. For information about how they work in general, see the Concepts Manual. Within top-level objects, QBFC groups some information into various other types of objects: basic aggregate objects (page 80), group objects (page 81), ORGroup objects (page 82), and list objects (page 84). Examples of Data Objects (page 86) shows how the QBFC message data objects can work in combination. Subscription and Event Callback Objects (page 87)

To determine which fields are required for any of the message data objects, you can use the Onscreen Reference.
NOTE Fields you access must be supported by the version of QuickBooks installed on each end-users computer and by the version of qbXML you specified in your call to the session managers CreateMsgSetRequest method (page 33).

Limiting Data Returned in Responses


There are potentially large amounts of data that can be returned in responses to requests. It is possible to explicitly specify the data that you want returned in the response by invoking IncludeRetElement one or more times on the request object you Appended to the message set, as shown in the following code snippet.
Dim CustomerQuery As ICustomerQuery Set CustomerQuery = msgSetRequest.AppendCustomerQueryRq() CustomerQuery.IncludeRetElementList.Add (FullName)

If this query is executed as-is, you would get all customers but only their FullNames. If you also wanted other data, such as CompanyName, you simply invoke IncludeRetElement a second time using CompanyName:
CustomerQuery.IncludeRetElementList.Add (CompanyName) Limiting Data Returned in Responses
(c) 2004 Intuit Inc. All rights reserved.

73

Just repeat this until you get the data you want in the response. Notice that no parsing is done on the strings supplied to IncludeRetElement. You must use valid names: refer to the Onscreen Reference for complete names that may be returned in the Responses.
IMPORTANT Only those items shown in the OSR Response pages can be used that are at the first level. Any indented items cannot be used. (In XML terms, standalone elements in XML can be used and also the parent aggregate.) That means the indented data (child aggregates) will be returned.

IQBBase
The IQBBase interface is implemented by all the other message data objects. It has one property: Type.

Type
HRESULT Type ([out, retval] IObjectType** pVal)

Returns the specific type of the object. You can get the type as either a string or an enum value. For example, if this were an ICustomerAdd object: You could use IObjectTypes GetAsString method to retrieve the objects type as a string, CustomerAdd, or You could use IObjectTypes GetValue method to retrieve the objects type as an enum value, otCustomerAdd. The COM enum type ENObjectType contains otCustomerAdd, as well as enum values for every other type of object that derives from IQBBase.

Add Objects
Add objects in QBFC correspond to qbXML Add requests, such as InvoiceAdd. The QBFC Add objects have properties that match all the fields in qbXML Add objects. The name of each Add object in QBFC starts with I followed by the name of the corresponding aggregate in qbXML. For example, the name of the object IInvoiceAdd in QBFC comes from the InvoiceAdd aggregate in qbXML. Example: IAccountAdd In qbXML, the AccountAdd request message has up to twelve fields: Two of the fields (Name and AccountType) are required. If you omit either of them, you will receive an error.

74 Chapter 5: Message Data Objects


(c) 2004 Intuit Inc. All rights reserved.

Two of the fields (IsActive and BankNumber) are not supported by QuickBooks Online Edition. If you try to add these fields to a QuickBooks Online Edition company file, the returned status code will be a warning that some fields were not supported and were ignored. One of the fields (DetailAccountType) is only supported by QuickBooks Online Edition. If you try to add this field to a QuickBooks desktop company file (U.S. or Canadian), you will receive a warning status code. Two of the fields (CurrencyRef and TaxCodeRef) are only supported by Canadian editions of QuickBooks. If you try to add these fields to a QuickBooks Online Edition or QuickBooks (U.S.) company file, you will receive an error.

The QBFC IAccountAdd object has the same twelve properties as AccountAdd, as Table 51 shows.
Table 5-1 Property Name IsActive ParentRef AccountType DetailAccountType AccountNumber BankNumber Desc OpenBalance OpenBalanceDate CurrencyRef TaxCodeRef IAccountAdd properties and their data types* QBFC Data Type IQBStringType IQBBoolType IQBBaseRef IQBENAccountTypeType IQBStringType IQBStringType IQBStringType IQBAmountType IQBDateType IQBBaseRef IQBBaseRef QBC only QBC only Not in QBOE Required IQBENDetailAccountTypeType Not in QBD Notes Required Not in QBOE

* The QBFC data types are described in Chapter 6, Data Type Objects.

Mod Objects
Mod (for Modify) objects in QBFC correspond to qbXML Mod requests, such as CustomerMod. The QBFC Mod objects have properties that match all the fields in the qbXML Mod objects. The name of each Mod object in QBFC starts with I followed by the name of the corresponding aggregate in qbXML. For example, the name of the object ICustomerMod in QBFC comes from the CustomerMod aggregate in qbXML.

Mod Objects 75
(c) 2004 Intuit Inc. All rights reserved.

Any field not specified in a Mod object will be left unchanged when QuickBooks processes the request. To clear a field (to empty it of its data), you would call its SetEmpty method before sending the request to QuickBooks. Example: IItemServiceMod In qbXML, the ItemServiceMod request message has up to seven fields: Two of the fields (ListID and EditSequence) are required. If you omit either of them, you will receive an error. Three of the fields (IsActive, SalesTaxCodeRef, and SalesAndPurchaseMod, which in QBFC is part of ORSalesPurchaseMod) are not supported by QuickBooks Online Edition. If you try to modify these fields in a QuickBooks Online Edition company file, the returned status code will be a warning that some fields were not supported and were ignored. One of the fields (TaxCodeRef) is only supported by Canadian editions of QuickBooks. For U.S. editions of QuickBooks, you would use SalesTaxCodeRef instead. If you try to modify SalesTaxCodeRef in a Canadian edition of QuickBooks, for example, you will receive an error.

The QBFC IItemServiceMod object has the same seven properties as the ItemServiceMod object in qbXML, as Table 5-2 shows.
Table 5-2 Property ListID EditSequence Name IsActive ParentRef SalesTaxCodeRef (TaxCodeRef in QBC) ORSalesPurchaseMod (SalesOrPurchaseMod or SalesAndPurchaseMod) Not in QBOE Not in QBOE IItemServiceMod properties and their data types* Notes Required Required QBFC Data Type IQBIDType IQBStringType IQBStringType IQBBoolType IQBBaseRef IQBBaseRef

(SalesAndPurchase IORSalesPurchaseMod Mod is not in QBOE) See ORGroup Objects (page 82).

* The QBFC data types are described in Chapter 6, Data Type Objects.

Del Objects
QBFC has two Del (for Delete) objects, IListDel and ITxnDel. These correspond to the two delete request messages in qbXML, ListDelRq and TxnDelRq.

76 Chapter 5: Message Data Objects


(c) 2004 Intuit Inc. All rights reserved.

IListDel
In qbXML, a list delete request contains two fields, ListDelType and ListID. The IListDel object in QBFC has the same two properties, both required.
NOTE In this context, list refers to a list of information in QuickBooks, such as a customer or account list. IListDel deletes a record from a list.
Table 5-3 Property ListDelType ListID IListDel properties and their data types* Notes Required Required QBFC Data Type IQBENListDelTypeType IQBIDType

* The QBFC data types are described in Chapter 6, Data Type Objects.

ITxnDel
In qbXML, a transaction delete request contains two fields, TxnDelType and TxnID. The ITxnDel object in QBFC has the same two properties, both required.
Table 5-4 Property TxnDelType TxnID ITxnDel properties and their data types* Notes Required Required Data Type IQBENTxnDelTypeType IQBIDType

* The QBFC data types are described in Chapter 6, Data Type Objects.

Void Objects
The Void object in QBFC, ITxnVoid, corresponds to the qbXML transaction void request message (TxnVoidRq).

ITxnVoid
In qbXML, a transaction void request contains two fields, TxnVoidType and TxnID. The ITxnVoid object in QBFC has the same two properties, both required.

Void Objects 77
(c) 2004 Intuit Inc. All rights reserved.

Table 5-5 Property TxnVoidType TxnID

ITxnVoid properties and their data types* Notes Required Required Data Type IQBENTxnVoidTypeType IQBIDType

* The QBFC data types are described in Chapter 6, Data Type Objects.

Ret Objects
Ret (for Return) objects in QBFC correspond to qbXML Ret response messages, such as InvoiceRet. The QBFC Ret objects have properties that match all the fields in the qbXML Ret objects. The name of each Ret object in QBFC starts with I followed by the name of the corresponding aggregate in qbXML. For example, the name of the object IInvoiceRet in QBFC comes from the InvoiceRet aggregate in qbXML. Any field in a Ret object that is not required (guaranteed) can be NULL (Nothing in VB). In the example below, ListID is a guaranteed field in an IAccountRet object, so its safe to call its GetValue method without first checking that it exists. This is not the case for a nonrequired (non-guaranteed) field, such as Balance. You can use the Onscreen Reference to determine which fields are guaranteed for any Ret object. Example: IAccountRet The IAccountRet object in QBFC has the same properties as the AccountRet message in qbXML, with the same implementation details: As Table 5-6 shows, six of the fields (for example, IsActive) will never be returned by QuickBooks Online Edition, because it doesnt support them. Fields that are newly supported for U.S. editions of QuickBooks (SpecialAccountType and CashFlowClassification in this case) arent yet supported in Canadian editions of QuickBooks, so Canadian editions wont return them. Two of the fields (CurrencyRef and TaxCodeRef) can only be returned by Canadian editions of QuickBooks. Two of the fields (DetailAccountType and LastCheckNumber) can only be returned by QuickBooks Online Edition.
IAccountRet properties and their data types* (page 1 of 2) Notes Required Required Required Required Data Type IQBIDType IQBDateTimeType IQBDateTimeType IQBStringType

Table 5-6 Property ListID

TimeCreated TimeModified EditSequence

78 Chapter 5: Message Data Objects


(c) 2004 Intuit Inc. All rights reserved.

Table 5-6 Property Name FullName IsActive ParentRef Sublevel AccountType

IAccountRet properties and their data types* (page 2 of 2) Notes Required Required Not in QBOE. Required Required Not in QBD. New in 2.1. Not in QBC. Not in QBOE. Not in QBOE. Not in QBD. Data Type IQBStringType IQBStringType IQBBoolType IQBBaseRef IQBIntType IQBENAccountTypeType IQBENDetailAccountTypeType IQBENSpecialAccountTypeType IQBStringType IQBStringType IQBStringType IQBStringType IQBAmountType IQBAmountType TaxLineInfoRet is new in 2.1. Not in QBOE. New in 2.1. Not in QBC. Not in QBOE. New in 2.0. Not in QBOE. ITaxLineInfoRet (or IQBBaseRef for CurrencyRef and TaxCodeRef) IQBENCashFlowClassificationType IDataExtRetList

DetailAccountType SpecialAccountType AccountNumber BankNumber LastCheckNumber Desc Balance TotalBalance TaxLineInfoRet (CurrencyRef and TaxCodeRef in QBC.) CashFlowClassification DataExtRetList

* The QBFC data types are described in Chapter 6, Data Type Objects.

Query Objects
Query objects are the objects that QBFC sends with query requests. For example, to query for information about bills that are in the QuickBooks company file, you would use the AppendBillQueryRq method to obtain a Query object, IBillQuery. The IBillQuery object doesnt have any required fields, but if you wanted to make your query specific, you could add data for some of its optional fields. Starting in SDK 4.0, a new metaData attribute is added to all queries. Possible values are mdMetaDataOnly or mdNoMetaData. By default, all queries use mdNoMetaData. However, if you want to get a pre-count of objects that would be returned in the query, specify mdMetaDataOnly in the metaData attribute. This is useful for determining whether you need to limit query responses using the MaxReturned feature of queries Query objects are named in the following way: Each Query object starts with I followed by the name of the related request in qbXML, without the Rq at the end. For example, the name IEmployeeQuery in QBFC comes from the EmployeeQueryRq request in qbXML.

Query Objects 79
(c) 2004 Intuit Inc. All rights reserved.

Like qbXML Add, Mod, Del, Void, or Ret objects, Query objects are the topmost objects in messages. The difference is that in qbXML, Query objects are not named. (For example, in qbXML, no EmployeeQuery aggregate is needed within an EmployeeQueryRq request.) Naming these objects in QBFC provides a convenient way to manage all the data a query request can contain.

The content of Query objects differs depending on the type of object being queried and the filtering criteria you use, and can be complex. Query objects typically contain several layers of objects, each of a different type, to account for all the ways to organize a query in qbXML. For examples of how to use query objects, see Examples of Data Objects (page 86). For more information on the logic of queries, refer to Chapter 3 of the Concepts Manual.

Basic Aggregate Objects


Each basic aggregate object in QBFC corresponds to an object reference or other low-level aggregate in qbXML. Higher-level QBFC objects can contain QBFC basic aggregates, which is also how it works in the underlying qbXML. The names of the basic aggregate properties themselves are identical to the corresponding aggregate names in qbXML. The QBFC object types that correspond to these properties follow this naming scheme: QBFC represents all qbXML object references, such as CustomerRef, with a single basic aggregate object, IQBBaseRef. QBFC represents most qbXML address aggregates (except for EmployeeAddress) with a single basic aggregate object, IAddress. All the other basic aggregate types are objects with the name I followed by the name of the corresponding aggregate in qbXML. For example, the object type name ITxnDateRangeFilter in QBFC comes from the TxnDateRangeFilter aggregate in qbXML.
Basic aggregate properties mapped to object type names QBFC Object Type IQBBaseRef IAddress

Table 5-7 shows how basic aggregate properties map to object types in QBFC.
Table 5-7 Basic Aggregate Properties All object references (properties that end in Ref), such as ParentRef and CustomerRef Address, BillAddress, ShipAddress, LegalAddress, VendorAddress, OtherNameAddress, CompanyAddressForCustomer All other basic aggregate properties

I followed by property name

80 Chapter 5: Message Data Objects


(c) 2004 Intuit Inc. All rights reserved.

Example: IQBBaseRef IQBBaseRef is used for all qbXML object references, which are used to refer to objects. An object reference can refer to either an object of the same type, which would be its parent, or an object of a different type.
Table 5-8 Property ListID FullName IQBBaseRef properties and their data types Data Type IQBDateType IQBStringType

In requests, unless the object reference is optional, at least one of the properties must be set. (If both are set, QuickBooks will use only the ListID.) In responses, both properties will be returned. In Add and Mod requests, the referenced object must already exist, unless its a list object defined earlier in an Add request in the same request set.

Group Objects
Each named group object in QBFC corresponds to an unnamed set of fields in qbXML. You will see group objects in the following places: Most group objects, such as ITxnDateFilter, appear in queries. Filter objects like this are integral to the logic of queries. For more about queries, see the Concepts Manual. Some group objects are part of a parent OR group. For example, the TxnDataExt group object is a child of ORListTxn, which is used in DataExt Add requests. Group objects are used for requests that dont require an aggregate in qbXML. For example, a TxnVoidRq message in qbXML consists of two elements that are not contained in an aggregate. In QBFC, these two fields are grouped together in the ITxnVoid group object.

Example: ITxnDateFilter The group object ITxnDateFilter can be used in any transaction query, for example in an InvoiceQuery request, to search for records within a given date range.

Group Objects 81
(c) 2004 Intuit Inc. All rights reserved.

Table 5-9 Property FromTxnDate ToTxnDate

ITxnDateFilter properties and their data types Data Type IQBDateType IQBDateType

ORGroup Objects
ORGroup objects in QBFC correspond to OR constructs in qbXML, which are sets of mutually exclusive fields. For example, Figure 5-1 shows an excerpt of the Onscreen Reference entry for the EntityQuery request, which can contain two ORGroup objects: IORListQuery and IORNameFilter. (EntityQuery requests are not supported by QuickBooks Online Edition.)

IORListQuery

IORNameFilter

Figure 5-1

The two ORGroup objects within the EntityQuery request specification, as shown in the Onscreen Reference

A QBFC entity query can contain at most one IORListQuery object, which can contain one or more ListID fields, or one or more FullName fields, or one IListFilter group object. > IListFilter can contain an IORNameFilter object. IORNameFilter can include either NameFilter or NameRangeFilter, but not both. (And if you include NameFilter, you must set both of the fields within it, as indicated by the Y following those fields in the table.)

82 Chapter 5: Message Data Objects


(c) 2004 Intuit Inc. All rights reserved.

If you set more than one of the mutually exclusive parts of an ORGroup, the object will fail verification when you call DoRequests or Verify. Every ORGroup object consists of several properties: The ortype property indicates which field, if any, was set most recently, and One property for every mutually exclusive field or group of fields in the corresponding qbXML OR construct.

For example, when viewing a CustomerQuery request in the Onscreen Reference, if you click IORNameFilter youll see three properties listed in the Onscreen Reference bottom frame: ortype, NameFilter, and NameRangeFilter. ORGroup objects follow this naming scheme: The name of each property that is an ORGroup starts with OR, for example, ORNameFilter. The name of the corresponding ORGroup type starts with IOR, for example, IORNameFilter. Each ortype property is implemented as a COM enum whose name starts with ENOR, for example, the name of the ortype property for the ORNameFilter object is ENORNameFilter.

NOTE If none of the mutually exclusive elements in an ORGroup have been set, the ortype property will have 1 as its value, corresponding to an enum name ending in NA, for not available. This will never be the case in Ret objects, however, because they do not contain ORGroup objects, such as ORNotes, when none of their mutually exclusive elements have been set.

Example: IORRate The ORGroup object called IORRate is used in many transactions and in Employee Add and Mod objects.
Table 5-10 Property Rate RatePercent ortype IORRate properties and their data types Data Type IQBPriceType IQBPercentType ENORRate

The read-only ortype property indicates whether Rate or RatePercent has been set most recently, or whether either element has been set at all. It returns a COM enum that can be one of three possible values: omRate, omRatePercent, or omNA (if neither element has been set).

ORGroup Objects 83
(c) 2004 Intuit Inc. All rights reserved.

List Objects
QBFC list objects correspond to repeating fields and repeating groups of fields in qbXML. QBFC uses list objects as a convenient way to manage these types of lists.
NOTE In other contexts in this book, the word list refers to the types of listed data in QuickBooks, such as customer and account lists.

QBFC has two types of list objects: Lists of objects, such as ICustomerRetList and IExpenseLineAddList, which correspond to repeating fields or repeating groups of fields in qbXML. > Each list of objects has a Count property, an Append method, and a GetAt method. The type of the parameter to the Append method and the type of the return value from the GetAt method will match the type of object in the list. The name of each list object is I, followed by the name of the corresponding aggregate in qbXML, followed by List. For example, the name of the list object IExpenseLineAddList in QBFC comes from the ExpenseLineAdd aggregate in qbXML that makes up the list.

>

See Example 1: IExpenseLineAddList, below. Lists of simple types, such as IBSTRList, and lists of enum values, such as IENAccountTypeList. > > Each list of simple types has the following methods and properties: Count, Add, AddAsString, GetAt, GetAtAsString, and Type. IBSTRList has the following functions: Add, Count, GetAt, GetMaxLength, Type.

See Example 2: IBSTRList, below. Example 1: IExpenseLineAddList IExpenseLineAddList consists of three methods and properties:
HRESULT Count ([out, retval] long* pVal)

This read-only property returns the number of IExpenseLineAdd objects that are in the list.
HRESULT Append ([out, retval] IExpenseLineAdd** retVal)

This method returns the IExpenseLineAdd object that has been appended to the list so you can initialize it according to the needs of the application. If this list is in a response, Append will return NULL (Nothing in VB).

84 Chapter 5: Message Data Objects


(c) 2004 Intuit Inc. All rights reserved.

NOTE A common mistake is to call Append over and over when trying to add multiple values to a single instance of an object. For example, to add an expense line that contains an amount, a customer, and a memo, you only need to call Append once, as the following VB code shows:
Dim obj ExpenseLine As IExpenseLineAdd Set obj ExpenseLine = obj BillAdd.ExpenseLineAddList.Append obj ExpenseLine.Amount.SetValue 35.00 obj ExpenseLine.CustomerRef.FullName.SetValue Robin Terry obj ExpenseLine.Memo.SetValue Blueprint copies for Darryl. HRESULT GetAt (long index, [out, retval] IExpenseLineAdd** retVal)

This method returns the zero-based index of the desired IExpenseLineAdd object within the list. GetAt will return an error code of 0x80040303 if the given index is out of range for this list. Example 2: IBSTRList IBSTRList consists of four methods and properties:
HRESULT Count ([out, retval] long* pVal)

This read-only property returns the number of strings in the list.


HRESULT Add ([in] BSTR addValue)

This method adds the specified string to the end of the list. Add will return an error code of 0x80040304 if the given string is longer than the maximum length allowed for the strings in this list. (For many strings, the maximum length is different for desktop versions of QuickBooks than for QuickBooks Online Edition.)
NOTE For IENAccountTypeList, Add will return an error code of 0x80040302 if the given account type enum value is not defined in qbXML.
HRESULT GetAt (long index, [out, retval] BSTR* retVal)

This method returns the zero-based index of the desired string within the list. GetAt will return an error code of 0x80040303 if the given index is out of range for this list.
HRESULT GetMaxLength ([out, retval] BSTR* pVal)

List Objects 85
(c) 2004 Intuit Inc. All rights reserved.

This method returns (as a string) the maximum allowed length of the strings in this list. If there is no maximum length, then it returns an empty string. (For many strings, the maximum length is different for desktop versions of QuickBooks than for QuickBooks Online Edition.)
NOTE GetMaxLength does not exist for IENAccountTypeList.

Examples of Data Objects


These queries give examples of how different kinds of objects can combine in QBFC. Example 1 This query looks for all employee records that have been modified since January 1, 2001, including records for employees who are no longer active:
Dim empQuery As QBFC4Lib.IEmployeeQuery empQuery.ORListQuery.ListFilter.FromModifiedDate. SetValue CDate(1/1/01) empQuery.ORListQuery.ListFilter.ActiveStatus.SetValue asAll

In this case, the Query object (IEmployeeQuery) contains an ORGroup (ORListQuery) that contains a group (ListFilter). Example 2 The query becomes more complex if it is changed to look for all employee records for employees whose names start with J:
Dim empQuery As QBFC4Lib.IEmployeeQuery empQuery.ORListQuery.ListFilter.ORNameFilter. NameFilter.MatchCriterion.SetValue mcStartsWith empQuery.ORListQuery.ListFilter.ORNameFilter. NameFilter.Name.SetValue "J"

The Query object still contains an ORGroup (ORListQuery) that contains a group (ListFilter). However, that group now contains another ORGroup (ORNameFilter), which in turn contains another group (NameFilter). Example 3 This query uses a list object to look for the employee records of two specific employees:
Dim empQuery As QBFC4Lib.IEmployeeQuery empQuery.ORListQuery.FullNameList.Add "Almira Smith" empQuery.ORListQuery.FullNameList.Add "Sisko Jones"

86 Chapter 5: Message Data Objects


(c) 2004 Intuit Inc. All rights reserved.

Here, the Query object still contains an ORGroup (ORListQuery), but now that ORGroup contains a list object (FullNameList) instead of a group (ListFilter).

Subscription and Event Callback Objects


Subscription objects (for example IDataEventSubscriptionAdd) are different from the other objects described in this chapter in that they are not related to QuickBooks company-file data. Instead, they are used to set up, query, and delete event subscriptions. The event-callback object (the IOREvents object in the QBXMLEvents message) provides the event information for your application during a callback. The IEventsMsgSet has two functions:
HRESULT OREvent([out, retval] IOREvent* *pVal); HRESULT ToXMLString([out, retval] BSTR* qbXMLResponse);

For more information, see Event Notification (page 54).

Subscription and Event Callback Objects


(c) 2004 Intuit Inc. All rights reserved.

87

88 Chapter 5: Message Data Objects


(c) 2004 Intuit Inc. All rights reserved.

CHAPTER 6 DATA TYPE OBJECTS

1 1

The QBFC data type objects, which correspond to qbXML data types, are wrappers for COM data types. This chapter describes the following topics: IBasicPropertyType (the interface from which all QBFC data type objects derive) The enum data type objects (page 90) The remaining data type objects, in alphabetical order: IQBAmountType, IQBBoolType, IQBDateType, IQBDateTimeType, IQBIDType, IQBIntType, IQBPercentType, IQBPriceType, IQBQuanType, IQBStringType, IQBTimeIntervalType, and IQBGuidType.

NOTE Information specific to an individual field (not its data type) can be found elsewhere. You can use the Onscreen Reference to determine which fields are required for any message data object.

IBasicPropertyType
The IBasicPropertyType interface is implemented by all data type objects. It has four methods: IsSet, IsEmpty, Unset, and SetEmpty. IsSet
HRESULT IsSet ([out, retval] VARIANT_BOOL* pVal)

Indicates whether or not the field corresponding to this object is set. It is considered set if it is set to a specific value or to empty via SetEmpty. This method returns True in VB and VARIANT_TRUE in C++ (the numeric representation of both is -1) if the field is set, and False in VB and VARIANT_FALSE in C++ (the numeric representation of both is 0) otherwise. IsEmpty
HRESULT IsEmpty ([out, retval] VARIANT_BOOL* pVal)

Indicates whether or not the field corresponding to this object is empty. It is considered empty only if it has been set to empty via SetEmpty. This method returns True in VB and VARIANT_TRUE in C++ (the numeric representation of both is -1) if the field is empty, and False in VB and VARIANT_FALSE in C++ (the numeric representation of both is 0) otherwise.

IBasicPropertyType 89
(c) 2004 Intuit Inc. All rights reserved.

Unset
HRESULT Unset ()

Removes the field corresponding to this object entirely. This is helpful, for example, if youve set a particular field in a request and then decided that you dont want it to be part of the request, after all. SetEmpty
HRESULT SetEmpty ()

Removes any data from this object, but the object will still be sent to QuickBooks if it is part of a request. This is helpful for Mod operations in which you want QuickBooks to clear a particular field of any data.

Enum Data Types


The QBFC Library has a different enum data type object for every unique ENUMTYPE in qbXML. For example, the enum object IQBENActiveStatusType represents the ActiveStatus ENUMTYPE in qbXML. The values in each enum object are internally mapped to the appropriate string values in qbXML. The enum data type objects in QBFC have names that start with IQBEN and end with Type, for example IQBENGenderType and IQBENListDelTypeType. The COM enum types they represent have names that start with EN, for example ENGender and ENListDelType. The enum values they contain have names that start with an abbreviation for the COM enum type. For example, IQBENActiveStatusType is an enum data type object, ENActiveStatus is the COM enum type it represents, and asActiveOnly is one of its possible values, with the as standing for active status. Each enum data type object has the same four methods. Two of these methods (SetValue and GetValue) have the corresponding COM enum type as the type of their input parameter or return value. These points are illustrated in the example below.

Example: IQBENActiveStatusType
IQBENActiveStatusType refers to the active status of a list element in QuickBooks. For example, if the value of ActiveStatus is set to asActiveOnly in a CustomerQuery request, the query will return only customers objects that are marked as active in QuickBooks. IQBENActiveStatusType, like all QBFC enum data type objects, has the following methods. SetValue
HRESULT SetValue ([in] ENActiveStatus val)

Sets the active status for use in a list query. It can be one of three values: asActiveOnly, asInactiveOnly, or asAll. An HRESULT of 0x80040302 will be returned if the given enum value is not defined by qbXML.
90 Chapter 6: Data Type Objects
(c) 2004 Intuit Inc. All rights reserved.

IMPORTANT We recommend against using numbers to set enum values, for example by using the function call SetValue(1) instead of SetValue(asActiveOnly). If your programming language makes it hard for you to use enum symbols (such as asActiveOnly), then use the SetAsString function described below instead of SetValue. That way your code will not be impacted if the order of the enum values changes in the SDK.

GetValue
HRESULT GetValue ([out, retval] ENActiveStatus* pVal)

Returns, as an enum value, the active status that has been set. It can be one of three values: asActiveOnly, asInactiveOnly, or asAll. An HRESULT of 0x80040300 will be returned if this property is retrieved before it has been set. An HRESULT of 0x80040306 will be returned if this property is retrieved after it has been set to empty. SetAsString
HRESULT SetAsString ([in] BSTR val)

Sets the active status for use in a list query. It can be one of three values: ActiveOnly, InactiveOnly, or All. An HRESULT of 0x80040302 will be returned if the given enum value is not defined by qbXML. GetAsString
HRESULT GetAsString ([out, retval] BSTR* pVal)

Returns, as a string, the active status that has been set. It can be one of three values: ActiveOnly, InactiveOnly, or All. An HRESULT of 0x80040300 will be returned if this property is retrieved before it has been set. An HRESULT of 0x80040306 will be returned if this property is retrieved after it has been set to empty.

IQBAmountType
The IQBAmountType object in QBFC implements the AMTTYPE in qbXML, and has the following restrictions: It can contain up to eight digits to the left of the decimal point. If it is manipulated as a double, it can contain up to two digits to the right of the decimal point. If it is manipulated as a string, it must contain exactly two digits to the right of the decimal point.

IQBAmountType 91
(c) 2004 Intuit Inc. All rights reserved.

IQBAmountType consists of the following methods: SetValue


HRESULT SetValue ([in] double val)

val HRESULT values:

The amount, which can contain up to eight digits to the left of the decimal point and up to two digits to the right of the decimal point.

An error code of 0x80040305 will be returned if the given amount is in an invalid format.

GetValue
HRESULT GetValue ([out, retval] double* pVal)

Returns, as a double, the amount that has been set. HRESULT values: An error code of 0x80040300 will be returned if this property is retrieved before it has been set. An error code of 0x80040306 will be returned if this property is retrieved after it has been set to empty.

SetAsString
HRESULT SetAsString ([in] BSTR val)

val

The amount, which can contain up to eight digits to the left of the decimal point, and it must contain exactly two digits to the right of the decimal point.

HRESULT values: An error code of 0x80040305 will be returned if the given amount is in an invalid format.

GetAsString
HRESULT GetAsString ([out, retval] BSTR* pVal)

Returns, as a string, the amount that has been set. HRESULT values: An error code of 0x80040300 will be returned if this property is retrieved before it has been set. An error code of 0x80040306 will be returned if this property is retrieved after it has been set to empty.

92 Chapter 6: Data Type Objects


(c) 2004 Intuit Inc. All rights reserved.

IQBBoolType
The IQBBoolType object in QBFC implements the BOOLTYPE in qbXML. It represents a Boolean (VARIANT_BOOL) value. IQBBoolType consists of the following methods: SetValue
HRESULT SetValue ([in] VARIANT_BOOL val)

val

The Boolean (VARIANT_BOOL) value, which is either True in VB and VARIANT_TRUE in C++ (the numeric representation of both is 1) or False in VB and VARIANT_FALSE in C++ (the numeric representation of both is 0).

GetValue
HRESULT GetValue ([out, retval] VARIANT_BOOL* pVal)

Returns the Boolean (VARIANT_BOOL) value that has been set. It will be either True in VB and VARIANT_TRUE in C++ (the numeric representation of both is -1) or False in VB and VARIANT_FALSE in C++ (the numeric representation of both is 0). HRESULT values: An error code of 0x80040300 will be returned if this property is retrieved before it has been set. An error code of 0x80040306 will be returned if this property is retrieved after it has been set to empty.

IQBDateType
The IQBDateType object in QBFC implements the DATETYPE in qbXML. It represents a date value. IQBDateType consists of the following methods: SetValue
HRESULT SetValue ([in] DATE val)

val GetValue

The date value. If the time is also included, it will be truncated.

HRESULT GetValue ([out, retval] DATE* pVal)

Returns the date value that has been set.

IQBBoolType 93
(c) 2004 Intuit Inc. All rights reserved.

HRESULT values: An error code of 0x80040300 will be returned if this property is retrieved before it has been set. An error code of 0x80040306 will be returned if this property is retrieved after it has been set to empty.

IQBDateTimeType
The IQBDateTimeType object in QBFC implements the DATETIMETYPE in qbXML. It represents a date-time value. IQBDateTimeType consists of the following methods: SetValue
HRESULT SetValue ([in] DATE val, [in] VARIANT_BOOL asDateOnly)

val asDateOnly

The datetime value. If the time is also included when asDateOnly is set to true, the value will be truncated. The Boolean (VARIANT_BOOL) value, which is either True in VB and VARIANT_TRUE in C++ (the numeric representation of both is 1) or False in VB and VARIANT_FALSE in C++ (the numeric representation of both is 0).

> >

If asDateOnly is true, the date value will be represented as a date only (without a time). If asDateOnly is false, the date value will be represented as date and time, padded with zeros if necessary, and set to the beginning of the day if no time is provided. If asDateOnly is set to true in the ToModifiedDate field of a query, then the query includes elements modified up to the end of the day. If asDateOnly is false, the query includes elements modified up to the specified time (or up to the beginning of the day if no time is included).

The asDateOnly parameter is especially useful in the ToModifiedDate field of a query: > >

GetValue
HRESULT GetValue ([out, retval] DATE* pVal)

Returns the datetime value that has been set. HRESULT values: An error code of 0x80040300 will be returned if this property is retrieved before it has been set. An error code of 0x80040306 will be returned if this property is retrieved after it has been set to empty.

94 Chapter 6: Data Type Objects


(c) 2004 Intuit Inc. All rights reserved.

SetTimeZone
HRESULT SetTimeZone([in]short hours, [in] short minutes);

hours minutes

These two parameters must be simultaneously positive or negative. For example (-5, 30) is not accepted. The hours must be between 12 and 12, and minutes must be between -59 and 59; otherwise, HRESULT 0x80040305 is returned. If no time zone is set, QuickBooks defaults to the local time zone.

The TimeZone value is removed by the Unset() or SetEmpty() methods. GetTimeZone


HRESULT GetTimeZone([out] short *hours, [out] short *minutes);

HRESULT values: An error code of 0x80040300 will be returned if no value has been set.

IQBFloatType
The IQBFloatType object in QBFC implements the FLOATTYPE type in the Canadian version of the 2.0 qbXML specification. IQBFloatType numbers have six significant digits, with a maximum of six digits after the decimal point. For example, an IQBFloatType number with three digits before the decimal point could have up to three digits after the decimal point. IQBFloatType consists of the following methods:
HRESULT HRESULT HRESULT HRESULT HRESULT HRESULT HRESULT HRESULT SetValue(single val) GetValue([out, retval] single* pVal) SetAsString(BSTR val) GetAsString([out, retval] BSTR* pVal) IsSet([out, retval] VARIANT_BOOL* pVal) IsEmpty([out, retval] VARIANT_BOOL* pVal) Unset() SetEmpty()

For more information about using the SDK with Canadian editions of QuickBooks, see Appendix B, Integrating with Canadian Editions of QuickBooks.

IQBFloatType 95
(c) 2004 Intuit Inc. All rights reserved.

IQBIDType
The IQBIDType object in QBFC implements the qbXML IDTYPE, which is a string up 36 characters long. Three of the IQBIDType methods (SetValueUseMacro, GetValueUseMacro, and IsSetUseMacro) are new with version 2.0, and relate to the useMacro attribute. Macros allow you to define an element (created in a new request), then use that element within the same message set (or anytime within the same session). For more information about macros, see the Concepts Manual. IQBIDType consists of the following methods: SetValue
HRESULT SetValue ([in] BSTR val)

val HRESULT values:

The ID string, up to 36 characters long.

An error code of 0x80040304 will be returned if the given ID string has more than 36 characters.

GetValue
HRESULT GetValue ([out, retval] BSTR* pVal)

Returns the ID string that has been set. HRESULT values: An error code of 0x80040300 will be returned if this property is retrieved before it has been set. An error code of 0x80040306 will be returned if this property is retrieved after it has been set to empty.

SetValueUseMacro
HRESULT SetValueUseMacro(BSTR val)

Use this method to set the useMacro attribute. HRESULT values: An error HRESULT of 80040300 is returned if the field cannot accept "useMacro."

GetValueUseMacro
HRESULT GetValueUseMacro([out, retval] BSTR *pVal)

Use this method to get the useMacro attribute.

96 Chapter 6: Data Type Objects


(c) 2004 Intuit Inc. All rights reserved.

HRESULT values: An error HRESULT of 80040300 is no "useMacro" has been set

IsSetUseMacro
HRESULT IsSetUseMacro([out, retval] VARIANT_BOOL *pVal);

Use this method to test whether the useMacro attribute can be set.

IQBIntType
The IQBIntType object in QBFC implements the INTTYPE in qbXML. It represents an integer value. IQBIntType consists of the following methods: SetValue
HRESULT SetValue ([in] long val)

val HRESULT values:

The integer value, up to the maximum value allowed for this particular field. Refer to GetMaxValue, below.

An error code of 0x80040303 will be returned if the given integer is greater than the maximum value allowed for this particular field. Refer to GetMaxValue, below.

GetValue
HRESULT GetValue ([out, retval] long* pVal)

Returns the integer value that has been set. HRESULT values: An error code of 0x80040300 will be returned if this property is retrieved before it has been set. An error code of 0x80040306 will be returned if this property is retrieved after it has been set to empty.

GetMaxValue
HRESULT GetMaxValue ([out, retval] BSTR* pVal)

Returns, as a string, the maximum value allowed for this particular field. If the field doesnt have a maximum allowed value, this method returns an empty string.

IQBIntType 97
(c) 2004 Intuit Inc. All rights reserved.

IQBPercentType
The IQBPercentType object in QBFC implements the PERCENTTYPE in qbXML. It can contain up to seven digits to the left of the decimal point and up to five digits to the right of the decimal point. IQBPercentType consists of the following methods: SetValue
HRESULT SetValue ([in] double val)

val HRESULT values:

The percent, which can contain up to seven digits to the left of the decimal point and up to five digits to the right of the decimal point.

An error code of 0x80040305 will be returned if the given percent is in an invalid format.

GetValue
HRESULT GetValue ([out, retval] double* pVal)

Returns, as a double, the percent that has been set. HRESULT values: An error code of 0x80040300 will be returned if this property is retrieved before it has been set. An error code of 0x80040306 will be returned if this property is retrieved after it has been set to empty.

SetAsString
HRESULT SetAsString ([in] BSTR val)

val HRESULT values:

The percent, which can contain up to seven digits to the left of the decimal point and up to five digits to the right of the decimal point.

An error code of 0x80040305 will be returned if the given percent is in an invalid format.

GetAsString
HRESULT GetAsString ([out, retval] BSTR* pVal)

Returns, as a string, the percent that has been set. HRESULT values: An error code of 0x80040300 will be returned if this property is retrieved before it has been set.

98 Chapter 6: Data Type Objects


(c) 2004 Intuit Inc. All rights reserved.

An error code of 0x80040306 will be returned if this property is retrieved after it has been set to empty.

IQBPriceType
The IQBPriceType object in QBFC implements the PRICETYPE in qbXML. It can contain up to eight digits to the left of the decimal point and up to five digits to the right of the decimal point. IQBPriceType consists of the following methods: SetValue
HRESULT SetValue ([in] double val)

val HRESULT values:

The price, which can contain up to eight digits to the left of the decimal point and up to five digits to the right of the decimal point.

An error code of 0x80040305 will be returned if the given price is in an invalid format.

GetValue
HRESULT GetValue ([out, retval] double* pVal)

Returns, as a double, the price that has been set. HRESULT values: An error code of 0x80040300 will be returned if this property is retrieved before it has been set. An error code of 0x80040306 will be returned if this property is retrieved after it has been set to empty.

SetAsString
HRESULT SetAsString ([in] BSTR val)

val HRESULT values:

The price, which can contain up to eight digits to the left of the decimal point and up to five digits to the right of the decimal point.

An error code of 0x80040305 will be returned if the given price is in an invalid format.

GetAsString
HRESULT GetAsString ([out, retval] BSTR* pVal)

Returns, as a string, the price that has been set.

IQBPriceType 99
(c) 2004 Intuit Inc. All rights reserved.

HRESULT values: An error code of 0x80040300 will be returned if this property is retrieved before it has been set. An error code of 0x80040306 will be returned if this property is retrieved after it has been set to empty.

IQBQuanType
The IQBQuanType object in QBFC implements the QUANTYPE in qbXML. It can contain up to seven digits to the left of the decimal point and up to five digits to the right of the decimal point. IQBQuanType consists of the following methods: SetValue
HRESULT SetValue ([in] double val)

val HRESULT values:

The quantity, which can contain up to seven digits to the left of the decimal point and up to five digits to the right of the decimal point.

An error code of 0x80040305 will be returned if the given quantity is in an invalid format.

GetValue
HRESULT GetValue ([out, retval] double* pVal)

Returns, as a double, the quantity that has been set. HRESULT values: An error code of 0x80040300 will be returned if this property is retrieved before it has been set. An error code of 0x80040306 will be returned if this property is retrieved after it has been set to empty.

SetAsString
HRESULT SetAsString ([in] BSTR val)

val HRESULT values:

The quantity, which can contain up to seven digits to the left of the decimal point and up to five digits to the right of the decimal point.

An error code of 0x80040305 will be returned if the given quantity is in an invalid format.

100 Chapter 6: Data Type Objects


(c) 2004 Intuit Inc. All rights reserved.

GetAsString
HRESULT GetAsString ([out, retval] BSTR* pVal)

Returns, as a string, the quantity that has been set. HRESULT values: An error code of 0x80040300 will be returned if this property is retrieved before it has been set. An error code of 0x80040306 will be returned if this property is retrieved after it has been set to empty.

IQBStringType
The IQBStringType object in QBFC implements the STRTYPE in qbXML. It represents a string value. IQBStringType consists of the following methods: SetValue
HRESULT SetValue ([in] BSTR val)

val HRESULT values:

The string value, up to the maximum length allowed for this particular field. Refer to GetMaxLength, below.

An error code of 0x80040304 will be returned if the given string is longer than the maximum length allowed for this particular field. Refer to GetMaxLength, below.

GetValue
HRESULT GetValue ([out, retval] BSTR* pVal)

Returns the string value that has been set. HRESULT values: An error code of 0x80040300 will be returned if this property is retrieved before it has been set. An error code of 0x80040306 will be returned if this property is retrieved after it has been set to empty.

GetMaxLength
HRESULT GetMaxLength ([out, retval] BSTR* pVal)

Returns, as a string, the maximum length allowed for this particular field. If the field doesnt have a maximum allowed length, this method returns an empty string. (For many strings, the maximum length is different for desktop versions of QuickBooks than for QuickBooks Online Edition.)
IQBStringType 101
(c) 2004 Intuit Inc. All rights reserved.

IQBTimeIntervalType
The IQBTimeIntervalType object in QBFC implements the TIMEINTERVALTYPE in qbXML. It represents a time interval, in minutes, up to 1440 minutes (24 hours). IQBTimeIntervalType consists of the following methods: SetValue
HRESULT SetValue (short hours, short minutes, short seconds)

Sets the time interval. There is no maximum. HRESULT values: An error code of 0x80040303 will be returned if the given time interval is less than 0.

GetValue
HRESULT GetValue ([out] short* hours, [out]short* minutes, [out]short* seconds)

Returns the time interval that has been set. HRESULT values: An error code of 0x80040300 will be returned if this property is retrieved before it has been set. An error code of 0x80040306 will be returned if this property is retrieved after it has been set to empty.

IQBGuidType
The IQBGuidType object in QBFC implements the GUIDTYPE data type in qbXML. It can be 0 (zero), or a globally unique identifier that takes the form
{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}

where X is a hexadecimal digit. IQBGuidType consists of the following methods: SetValue


HRESULT SetValue (BSTR val)

val

Set to 0 for custom fields (data extensions that are visible in the QuickBooks user interface) or GUID for data extensions that your application owns.

GetValue
HRESULT GetValue ([out, retval] BSTR *pVal)

102 Chapter 6: Data Type Objects


(c) 2004 Intuit Inc. All rights reserved.

APPENDIX A ERROR CODES

1 1

Table A-1 lists the HRESULT error codes in QBFC and gives a brief description of each one. The QBSessionManager and QBOESessionManager objects support the IErrorInfo interface, so you can use IErrorInfo to get more information about most of the HRESULT values that the QBFC methods and properties return.
Table A-1 HRESULT 0x80040300 0x80040301 0x80040302 0x80040303 0x80040304 Description Attempted to retrieve a value before it has been set. Internal error interpreting the response. The given enum value is invalid. The given numeric value is out of range. The given string is longer than the maximum length allowed. (Note that for many strings, the maximum length is different for desktop versions of QuickBooks than for QuickBooks Online Edition.) The given value has an invalid format. Attempted to retrieve a value that has been set to empty. This message will indicate why the verification of the request set failed. Could not communicate with the QuickBooks SDK. The QuickBooks SDK is a pre-release version. The given version of qbXML is not supported. This feature is not supported in the specified version of qbXML. This message set must be used with the QBSessionManager, not QBOESessionManager. or This message set must be used with the QBOESessionManager, not QBSessionManager. (HTTP-specific error text.) (Specific error-recovery messages will be sent with this HRESULT.) This function is supported by a newer version of Request Processor. Error recovery is enabled. Process or clear the saved Response status before issuing another request. The ConnectionTicket must be filled in. The Country value is invalid. The mode of communication has already been established, and once set, it cannot be changed Cannot create QBXMLRP2e COM component. QuickBooks could not interpret the request. Could not access QuickBooks. Unexpected error. Check the qbsdklog.txt file for possible, additional information. Could not open specified QuickBooks company data file. HRESULT error codes

0x80040305 0x80040306 0x80040307 0x80040308 0x80040309 0x8004030A 0x8004030B 0x8004030C

0x8004030D 0x8004030E 0x8004030F 0x80040310 0x80040311 0x80040312 0x80040313 0x80040314 0x80040400 0x80040401 0x80040402 0x80040403

103
(c) 2004 Intuit Inc. All rights reserved.

Table A-1 HRESULT 0x80040404 0x80040405 0x80040406 0x80040407 0x80040408 0x80040409 0x8004040A 0x8004040B 0x8004040C 0x8004040D 0x8004040E 0x8004040F 0x80040410 0x80040411 0x80040412 0x80040413 0x80040414 0x80040415 0x80040416 0x80040417 0x80040418 Description

HRESULT error codes

The version of QuickBooks currently running does not support QBXML. QBXML components have not been installed. Could not determine the QuickBooks company data file version, or the data file has been modified and might be a newer version of QuickBooks. The installation of QuickBooks appears to be incomplete. Please reinstall QuickBooks. Could not start QuickBooks. The version of QuickBooks currently running cannot work with the provided company data file. There is already a company data file open and it is different from the requested one. Internal Error. Could not get the current company data file name. BeginSession method has not been called or it did not succeed. The session expired. There is not enough memory to complete the request. OpenConnection has not been called. The data file is currently open in a mode other than the one specified by your application. EndSession must be called before the next BeginSession. Multiple successive calls to OpenConnection are invalid. Call CloseConnection after each OpenConnection before calling OpenConnection again. QuickBooks does not support the Rollback on Error attribute. QuickBooks is currently locked in a modal state and cannot be accessed. The application name must be supplied to OpenConnection. If QuickBooks is not running, the company data file name must be supplied to BeginSession. If the company data file is not open, the data file name must be supplied to BeginSession. This application has not accessed this QuickBooks company data file before. Only the QuickBooks administrator can grant an application permission to access a QuickBooks company data file for the first time. This applications certificate is invalid. An application must have a valid certificate to access QuickBooks company data files. Access denied. This application does not have permission to access this QuickBooks company data file. If access is required, the QuickBooks administrator can grant permission through the Integrated Application preferences. Unable to lock the necessary information to allow this application to access this company data file. Try again later. An internal QuickBooks error occurred while trying to access the company data file. This application is not allowed to log into this QuickBooks company data file automatically. If automatic login is required, the QuickBooks administrator can grant permission through Integrated Application preferences. For more information, see More Information about Login Modes (page 25) and Permissions Required for Auto-Login (page 80). This applications certificate is expired. If you want to allow the application to log into QuickBooks automatically, log into QuickBooks and try again. Then click Allow Always when you are notified that the certificate has expired. QuickBooks Basic cannot accept API requests. Another product in the QuickBooks line, such as QuickBooks Pro or Premier, is required.

0x80040419 0x8004041A

0x8004041B 0x8004041C 0x8004041D

0x8004041E

0x8004041F

104 Appendix A: Error Codes


(c) 2004 Intuit Inc. All rights reserved.

Table A-1 HRESULT 0x80040420 0x80040421 0x80040422 Description

HRESULT error codes

Access denied by the user. This message will come directly from QuickBooks. This application requires single-user file access mode and there is another application already accessing the specified QuickBooks company data file. The error message indicates that multiple applications that require single-user file access mode cannot begin sessions with QuickBooks simultaneously. The given version of qbXML is not supported by the QuickBooks SDK. QuickBooks did not finish its initialization. Please try again later. An invalid parameter has been passed in; for example, a NULL pointer was passed in when a valid pointer was expected. Scripts are not allowed to call the QuickBooks SDK. The QuickBooks application needs to be registered. The version of QBXML that was requested is not supported by this version of the QBXMLRP library The message set requested cannot be processed through the API that was called. This call may not be made from a remote system. Unsupported interface. Certificate has been revoked. QuickBooks did not finish opening the data file while launching its UI, and we decided to give up. Perhaps the user did not complete the QuickBooks login process. This call cannot be made after calling "BeginSession" and before calling "EndSession". The requested connection type could not be found.

0x80040423 0x80040424 0x80040425 0x80040426 0x80040427 0x80040428 0x80040429 0x8004042A 0x8004042B 0x8004042C 0x8004042D 0x8004042E 0x8004042F

105
(c) 2004 Intuit Inc. All rights reserved.

106 Appendix A: Error Codes


(c) 2004 Intuit Inc. All rights reserved.

APPENDIX B INTEGRATING WITH CANADIAN EDITIONS OF QUICKBOOKS

1 1

The QBFC API is supported by Canadian editions of QuickBooks, U.S. editions of QuickBooks, and QuickBooks Online Edition. Table B-1 shows the correspondence between QBFC versions and Canadian editions of QuickBooks.
Table B-1 QBFC support in Canadian editions of QuickBooks How is it supported by Canadian editions of QuickBooks? Not supported by Canadian editions. Supported by 2003 Canadian editions. Not supported by Canadian editions. Supported by 2003, 2004, and 2005 Canadian editions. New SDK 4.0 features not supported by 2005 Canadian editions.

Version of QBFC QBFC1 QBFC2CA QBFC2_1 QBFC3 QBFC4

QBFC Features Unique to Canada


The biggest ways in which Canadian and U.S. editions of QuickBooks differ is that the Canadian editions accommodate Canadian tax structures and the use of multiple currencies: Canadian editions of QuickBooks include a Tax Code list that makes it easier to work with Canada-specific taxes. You can add taxes to this list, modify the list, query the list, and delete tax codes from the list. You can also assign these tax codes to QuickBooks list and transaction objects. Canadian editions of QuickBooks include a Currency list that is available when the user has turned on the multi currency preference. You can add currencies to this list, modify the list, query the list, and delete currencies from the list. You can also include currency-related information in QuickBooks list and transaction objects.

The rest of this section gives more details about the differences.

Tax Differences
Integrating with Canadian editions of QuickBooks, you would not use any information related to sales taxes or sales tax codes. Instead, you would use Tax 1 and Tax 2. Tax 1 is used for Goods and Services Tax, or GST. Tax 2 is used for Provincial Sales Taxes, or PST.

QBFC Features Unique to Canada 107


(c) 2004 Intuit Inc. All rights reserved.

Related QBFC messages: TaxCodeAdd request and response (ITaxCodeAdd and ITaxCodeRet QBFC objects) TaxCodeMod request and response (ITaxCodeMod and ITaxCodeRet QBFC objects) TaxCodeQuery request and response (ITaxCodeQuery and ITaxCodeRetList QBFC objects)

Related QBFC object references: TaxCodeRef CustomerTaxCodeRef DefaultCustomerTaxCodeRef Tax1AgencyRef Tax2AgencyRef

Related QBFC fields: Tax1Rate and Tax2Rate Tax1Total and Tax2Total Tax1Number andTax2Number ChargeTax1 and ChargeTax2 TrackTax1Expenses and TrackTax2Expenses Tax1ReportingPeriod and Tax2ReportingPeriod AllowCustomerTaxCodes AmountIncludesVAT IsTax1Exempt and IsTax2Exempt (Boolean values that are true for items exempt from Tax 1 or Tax 2) IsPiggyBackRate (Boolean value that is true when Tax 2 is partly determined by Tax 1)

Employee and Address Information


Integrating with Canadian editions of QuickBooks, you would not use any information about social security numbers (SNNs). Instead, you would use information about social insurance numbers (SINs). Related QBFC field: SIN

Integrating with Canadian editions of QuickBooks, you would not use any information about state information in addresses. Instead, you would use province information in addresses. Related QBFC field: Province

108 Appendix B: Integrating with Canadian Editions of QuickBooks


(c) 2004 Intuit Inc. All rights reserved.

Integrating with Canadian editions of QuickBooks, you would not use any information about 1099 forms. Instead, you would use information about statement of income (T4A) forms. Related QBFC field: IsVendorEligibleForT4A

Exchange Rates and Currency The QBFC data type IQBFloatType is used for the ExchangeRate field, which describes international exchange rates. For more information, see IQBFloatType (page 95). QBFC gives you a means to access the Currency list and also to include currency information in some list and transaction objects. Related new messages: CurrencyAdd request and response (ICurrencyAdd and ICurrencyRet QBFC objects) CurrencyMod request and response (ICurrencyMod and ICurrencyRet QBFC objects) CurrencyQuery request and response (ICurrencyQuery and ICurrencyRetList objects)

Related new fields: ExchangeRate Symbol Code CurrencyHotKey SymbolPos DecimalSep DecimalPlaces ThousandSep ForeignPrice

Related new object references: CurrencyRef HomeCurrencyRef (returned by the IPreferencesRet object) ForeignCurrencyRef (returned by the IPreferencesRet object)

Currency information is returned by PreferencesQuery messages. Related QBFC fields: IsUsingForeignPricesOnItems IsUsingMulticurrency IsUsingUnitsOfMeasure (For more information, see About Units of Measure, below.)

QBFC Features Unique to Canada 109


(c) 2004 Intuit Inc. All rights reserved.

Related QBFC object references: HomeCurrencyRef ForeignCurrencyRef

QBFC includes a few U.K.-specific fields that are related to European currencies. Related fields: IsECVatCode IsEmu EmuRate

About Units of Measure


A Units of Measure feature is available in Canadian editions of QuickBooks, but you currently cant access it through the SDK. The SDK does already give you a way to find out whether a QuickBooks file has the Units of Measure preference turned on, however. To find out: 1. Use the AppendPreferencesQueryRq method to request information about preferences that the QuickBooks user has set in the company file. 2. Examine the returned PreferencesRet object. In the SalesAndCustomersPreferences object, check whether the IsUsingUnitsOfMeasure field is set to true. If the Units of Measure preference is turned on, an interactive user might specify inventory units, sales units, and purchasing units for inventory and assembly items, even though you cannot retrieve any of this information through the SDK. For example, imagine a QuickBooks file that has an inventory item called soup and is set up with this Units of Measure information: Inventory unit: case Sales unit: can, at 12 cans/case Purchasing unit: flat, at 2 cases/flat

Given this set up, an invoice selling 3 cans of soup would reduce inventory by .25 cases (based on the relationship of 12 cans per case). Purchasing 1 flat would increase inventory by 2 cases. But your application could not make sense of this data without the (irretrievable) background information about inventory units, sales units, and purchasing units. This means an SDK query on transactions and items might return unpredictable results. For this reason, if your application relies on this kind of data from transactions, we recommend that you do the following: 1. Design your application to check (as described above) whether the Units of Measure preference is turned on. 2. If the Units of Measure feature is on, consider sending a message that asks your users not to use it.

110 Appendix B: Integrating with Canadian Editions of QuickBooks


(c) 2004 Intuit Inc. All rights reserved.

About UI Integration
If you have two versions of your application, one for Canadian editions of QuickBooks and one for U.S. editions of QuickBooks, and you are integrating with the QuickBooks user interface (UI), note these important limitations: It is possible that a user who selects your UI extension from within a Canadian edition of QuickBooks will be taken to the U.S. version of your application, and vice versa. You cannot create a subscription on one machine such that a UI item added to U.S. editions of QuickBooks will invoke the U.S. version of your application while that same UI item in Canadian editions of QuickBooks will invoke the Canadian version of your application. Instead, each version of the application will overwrite any existing subscription, so that the last one installed wins. If you have a U.S.-only application, you cannot prevent your UI items from showing up in Canadian editions of QuickBooks. Conversely, if you have a Canada-only application, you cannot have a UI item that only shows up in Canadian editions of QuickBooks. UI extensions show up in all editions of QuickBooks.

For more information about UI integration, see the Concepts Manual.

About UI Integration 111


(c) 2004 Intuit Inc. All rights reserved.

112 Appendix B: Integrating with Canadian Editions of QuickBooks


(c) 2004 Intuit Inc. All rights reserved.

INDEX OF QBFC FUNCTIONS

A
AppendDataEventSubscriptionAddRq 66 AppendDataEventSubscriptionQueryRq 66 AppendSubscriptionDelRq 66 AppendUIEventSubscriptionAddRq 66 AppendUIEventSubscriptionQueryRq 66 AppendUIExtensionSubscriptionAddRq 66 AppendUIExtensionSubscriptionQueryRq 66 AppID 52 ApplicationLogin 51 AppVer 52 Attributes 59, 67 AuthID 52

GetMaxValue 97 GetSavedMsgSetRequest 38 GetTimeZone 95 GetValue example 91 See Chapter 6, "Data Type Objects." GetValueUseMacro 96 GetVersion 34

I
InstallationID 51 IsEmpty 89, 95 IsErrorRecoveryInfo 36 IsSet 89, 95 IsSetUseMacro 97

B
BeginSession 39

C
ClearErrorRecovery 37 ClearRequests 60, 65 CloseConnection 39 ConnectionTicket 51 ConnectionType 46 Count 62, 68 CreateMsgSetRequest 33 CreateSubscriptionMsgSetRequest 43 Detail 63, 70 DoRequests 34 DoRequestsFromXMLString 36 DoSubscriptionRequests 45 DoSubscriptionRequestsFromXMLString 44

Language 52

M N

MessageSetStatusCode 72 NewMessageSetID 64, 71

OldMessageSetID 64 OnError 63 OpenConnection 38 OREvent 87

Q R

QBXMLVersionsForSession 42 RequestID 63 ResponseData 65 ResponseList 67, 72 SaveAllMsgSetRequestInfo 37 SessionTicket 52 SetAsString example 91 See Chapter 6, "Data Type Objects." SetEmpty 90, 95 SetTimeZone 95

E
EnableErrorRecovery 37 EndSession 41 ErrorRecoveryID 37

G
GetAsString example 91 See Chapter 6, "Data Type Objects." GetAt 62, 68 GetCurrentCompanyFileName 42 GetErrorRecoveryStatus 38 GetMaxLength 101

QBFC3 Functions 113


(c) 2004 Intuit Inc. All rights reserved.

SetValue example 90 See Chapter 6, "Data Type Objects." SetValueUseMacro 96 StatusCode 69 StatusMessage 70 StatusSeverity 69

T
ToEventsMsgSet 45 ToMsgSetRequest 36 ToMsgSetResponse 35 ToSubscriptionMsgSetResponse 44 ToXMLString 60, 65, 68, 72, 87 Type 63, 71

U V

Unset 90, 95 Verify 60, 65

114 QBFC3 Functions


(c) 2004 Intuit Inc. All rights reserved.

INDEX OF TOPICS

A
AccountNumber property 79 AccountType property 79 Add method 85 Add objects 74 adding a customer (sample program) code 6 description 5 using with Canadian editions of QuickBooks 9 using with QuickBooks Online Edition 8 advantages, of single-user mode 28 aggregate objects 80 AllowCustomerTaxCodes elements 108 AmountIncludesVAT elements 108 AMTTYPE in qbXML 91 API choice of xii Append methods in lists that contain objects 84 in message set requests 10 naming of 10 need to call only once 84 of the subscription request object 66 AppendCustomerAddRq method (example) 61 appID parameter (application ID) in OpenConnection 38 AppID property 52 ApplicationLogin property 51 appName parameter in OpenConnection 39 AppVer property 52 Attributes property in IMsgSetRequest 59 in IMsgSetResponse 67 AuthID method 52 authorizing your application 21 auto-login to QuickBooks 25 automated error recovery about 53 and query requests 54 steps for using 53

in the sample program 8 syntax 39 BillAdd sample 4 BOOLTYPE in qbXML 93 building requests 9

C
C# sample code where to find more xi C++ sample code in this book 55 C++ sample code, where to find xi callback from a subscribed event 56 Canadian editions of QuickBooks about 1, 107 and CreateMsgSetRequest 33 Currency list in 109 integrating with 9, 107 Tax Code list in 108 using the Onscreen Reference for 4 changing a QuickBooks transaction or list element 75 ChargeTax1 elements 108 ChargeTax2 elements 108 checking responses 11 ClearRequests method 60, 65 CloseConnection method in the sample program 8 syntax 39 Code elements (currency code) 109 communicating with QuickBooks 8 ConnectionTicket property 51 conventions used in this manual xii Count property in IBSTRList 84, 85 in IExpenseLineAddList 84 in IResponseList 68 CreateMsgSetRequest method 33 example 10 syntax 33 Currency list objects 109 CurrencyHotKey elements 109

B
Balance property 79 basic aggregate objects 80 BeginSession method

data event recovery 54 data type objects 15


Index 115
Copyright 2003 Intuit Inc. All rights reserved.

enum 90 and qbXML 14 SetAsString method 91100 SetValue method 90102 DataEventRecoveryDel 57 DataEventRecoveryInfoQuery 57 DataEventRecoveryTime 57 DataExtRetList property 79 DATETIMETYPE in qbXML 94 DATETYPE in qbXML 93 DecimalPlaces elements 109 DecimalSep elements 109 Del objects 76 deleting list and transaction objects 76 Desc property 79 Detail property 70 Developers Guide for QuickBooks Online Edition 4 disadvantages, of single-user mode 28 distributing your application 18 DoRequests method building a new request set after calling 11 example 11 syntax 34 DoRequestsFromXMLString method 36

IQBBaseRef 81 IQBENActiveStatusType 90 ITxnDateFilter 81 of objects 86 query 86 ExchangeRate elements 109 exclusive access, to QuickBooks 28

F
filters represented by group objects 81 within Query objects 80 FLOATTYPE in qbXML (Canada only) 95 ForeignPrice elements 109 FromTxnDate property 82 FullName property 79, 81

G
GetAsString method (used by data type objects)

91101

GetAt method 68, 85 GetCurrentCompanyFileName method 42 GetMaxLength method 85, 101 GetMaxValue method 97 GetTimeZone method 95 GetValue method (used by data type objects)

92??, 92102

EditSequence property 78 EmuRate elements 110 EndSession method 41 end-users installing QBFC 5, 18 enum data types 90 ENUMTYPE in qbXML 90 error codes, HRESULT 103 error recovery (QBFC) about 53 and query requests 54 steps for using 53 European currencies 110 event notification 54 event recovery 57 message set xii, 65, 72 event recovery 57 examples adding a customer 5, 8, 9 IAccountAdd 74 IAccountRet 78 IBSTRList 85 IExpenseLineAddList 84 IItemServiceMod 76 IORNotes 83

GetValueUseMacro method GetVersion method 34 group objects 81 GUIDTYPE in qbXML 102

96

high-level request objects 15, 59 high-level response objects 15, 67 HostQuery requests versus QBXMLVersionsForSession HRESULT error codes 103

42

IAccountAdd example 74 IAccountRet example 78 IAddress object type 80 IAttributeRqSet object 63 IAttributesRsSet object 71 IBasicPropertyType interface 89 IBSTRList example 85 IDTYPE in qbXML 96 IErrorInfo interface 29, 103 IExpenseLineAddList example 84 IItemServiceMod example 76 IListDel object 77 IMsgSetRequest object 59

116 Index
Copyright 2003 Intuit Inc. All rights reserved.

IMsgSetResponse object 67 InstallationID property 51 installing and distributing your application 18 QBFC 5 integrating with multiple countries 9 interacting with QuickBooks 7 interactive login to QuickBooks 25 INTTYPE in qbXML 97 inventory units, not supported via SDK 110 IObjectType object 74 IORNotes example 83 IQBAmountType object 91 IQBBase interface 74 IQBBaseRef aggregate properties 80 example 81 IQBBoolType object 93 IQBDateTimeType object 94 IQBDateType object 93 IQBENActiveStatusType example 90 IQBFloatType data type object (Canada only) 95,

L
Language property 52 list objects about 84 adding 74 deleting 77 modifying 75 ListDelType property 77 ListID property in basic aggregate objects 81 in Del objects 77 in Mod objects 76 in Ret objects 78 lockout 28 login modes (in QuickBooks) 25 lost data events 56, 57 lost events 54

M
macros 96 memory freeing 43 merge modules 19 message data objects 15 MessageSetStatusCode property 72 migrating to QBFC3 2 Mod objects 75 modes single-user vs. multi-user 27 modifying lists and transactions 75 MSI (Microsoft Installer) 19 multicurrency 107 multi-user mode 27 effects of 27

109

IQBGuidType 102 IQBIDType object 96 IQBIntType object 97 IQBPercentType object 98 IQBPriceType object 99 IQBQuanType object 100 IQBStringType object 101 IQBTimeIntervalType 102 IResponse object 69 IResponseList object 68 IResponseType object 71 IsActive property 79 IsECVatCode elements 110 IsEmpty method 89 IsEmu elements 110 IsPiggyBackRate elements 108 IsSet method 89 IsSetUseMacro method 97 IsTax1Exempt elements 108 IsTax2Exempt elements 108 ISubscriptionMsgSetRequest object xii, 65 ISubscriptionMsgSetResponse object xii, 72 IsUsingForeignPricesOnItems elements 109 IsUsingMulticurrency elements 109 IsUsingUnitsOfMeasure elements 109 IsVendorEligibleForT4A elements 109 ITxnDateFilter example 81 ITxnDel object 77 ITxnVoid object 77

N
Name property 79 NewMessageSetID property

64, 71

O
objects Add 74 basic aggregate 80 categories of 14 Del 76 examples 86 group 81 list 84 Mod 75 ORGroup 82 query 79 Ret 78 viewing with IntelliSense 16
Index 117
Copyright 2003 Intuit Inc. All rights reserved.

viewing with the Onscreen Reference 17 Void 77 OldMessageSetID property 64 OnError property 63 Onscreen Reference and Canadian editions of QuickBooks 4 and QuickBooks Online Edition 4 how to use 17 OpenConnection method 38 ORGroup objects 82 ortype property 83

QuickBooks communicating with 8 sending requests to 11 QuickBooks Online Edition about 3 communicating with 8, 29, 33 functions of QBOESessionManager 32 IAccountAdd example 75, 76, 78 maximum string lengths 85, 101 support limited to desktop applications 3 ToXMLString returns signon messages for 60, using the Onscreen Reference with 4, 17 using with the sample in this book 8, 9 QuickBooks SDK Onscreen Reference 17

P
packaging your application 18 ParentRef property 79 PERCENTTYPE in qbXML 98 personal data 27 PRICETYPE in qbXML 99 problems accessing company data, in single-user mode 28 Province elements 108 purchasing units, not supported via SDK 110

68

R
redistributing SDK components 18 registering your application 18 requests building a set of 9 sending 11 ResponseData property 65 ResponseList method 72 ResponseList property 67 responses, checking 11 Ret objects 78

QBFC2_1 in CreateMsgSetRequest 33 QBFC3 about 1 and CreateMsgSetRequest 10, 33 installing 5 Onscreen Reference 17 whats new ix QBFC3Lib with IntelliSense 16 QBOESessionManager object (for QuickBooks Online Edition) 29, 33, 51 list of functions 32 QBSessionManager object (for QuickBooks desktop) 29, 33, 38 list of functions 29 qbXML Canadian form of 110 data types 14 setting which version a request will use 10, 33 QBXMLVersionsForSession method syntax 42 versus HostQuery request 42 QUANTYPE in qbXML 100 query example 86 Query objects 79 query requests, disabling error recovery before

sales units, not supported via SDK 110 sample code, where to find xi sample for QBOE (BillAdd), where to find 4 sample program (adding a customer) code 6 description 5 using with Canadian editions of QuickBooks 9 using with QuickBooks Online Edition 8 See also examples. sending a request set 11 server applications 3 session manager 29 sessions creating 8 ending 13 management of 15, 29 SessionTicket property 52 SetAsString method (used by data type objects)

91100

SetEmpty method 90 SetTimeZone method 95 SetValue method (used by data type objects)

90102

54
118 Index
Copyright 2003 Intuit Inc. All rights reserved.

SetValueUseMacro method

96

sign-on messages for QuickBooks Online Edition (ToXMLString) 60, 68 SIN elements 108 single-user mode 27 advantages and disadvantages of 28 effects of 27 software versions 3 Solutions Marketplace 18 stand-alone installers 19 StatusCode property 69 StatusMessage property 70 StatusSeverity property 69 STRTYPE in qbXML 101 Sublevel property 79 subscription high-level request object xii, 65 high-level response object xii, 72 switching to QBFC3 2 Symbol elements 109 SymbolPos elements 109

UI integration 54 unattended mode (of QuickBooks login) 25 unified QBFC3 ix, 9 units of measure, not supported via SDK 110 Unset method 90 unsupported features 2 useMacro attribute 96 using the stand-alone installers 19

V
VB sample code, where to find xi VB.NET sample code, where to find xi Verify method 60, 65 version migrating to QBFC3 2 of QBFC 1 setting with CreateMsgSetRequest 10, Void objects 77 voiding transaction objects 77

33

W
whats new in this guide xiii

Tax elements 108 TaxCode objects list 108 ThousandSep elements 109 TimeCreated property 78 TIMEINTERVALTYPE in qbXML 102 TimeModified property 78 timezone, setting and getting 95 ToMsgSetResponse method 35 tools for installing your application 19 Onscreen Reference 17 TotalBalance property 79 ToTxnDate property 82 ToXMLString method 60, 65, 68, 72 TrackLostEvents 57 TrackTax1Expenses elements 108 TrackTax2Expenses elements 108 transaction objects adding 74 deleting 77 modifying 75 voiding 77 TxnDelType property 77 TxnID property 77, 78 TxnVoidType property 78 Type 74 Type property 71, 74

U.K.-specific elements UI extensions 54

110
Index 119
Copyright 2003 Intuit Inc. All rights reserved.

120 Index
Copyright 2003 Intuit Inc. All rights reserved.

You might also like