QuickBooks Integrator 2020 C++ Edition

Questions / Feedback?

QBConnector Class

Properties   Methods   Events   Configuration Settings   Errors  

The QBCONNECTOR class is a utility that allows you to connect your QuickBooks Integrator applications to remote QuickBooks instances.

Syntax

QBConnector

Remarks

The QBConnector class is a lightweight web server which listens for HTTP requests originating from the QuickBooks Integrator classs. Each request sent to the QBConnector by a QuickBooks Integrator class contains the XML data to be communicated to QuickBooks as well as configuration settings specifying how the connection is to be opened. The QBConnector then communicates with QuickBooks via COM, and returns the QuickBooks response (or an error message) in the HTTP reply.

Using the QBConnector class is easy. Simply set Listening to True, and the class will begin listening for incoming messages on the specified LocalPort. The messages will be processed by the QuickBooks application that is running on the same machine as the QBConnector, and the results will automatically be returned to the requesting client.

Basic authentication is enabled by default, meaning the connecting clients must present a user name and password in the QBConnectionString of the class they're using. The supplied user name and password are checked against the list of AuthorizedUsers. If no user in the list matches the supplied credentials, the Authorization event will fire with the Accept parameter set to false. If the user was found in the list of AuthorizedUsers then the parameter will be set to True. You may override this functionality by setting the Accept parameter inside the Authorization event manually. If no "Authorization" header supplied in the request, the Authorization event will fire with blank User and Password parameters.

Note that the AuthorizedUserQBConnectionString will be used to make the connection to QuickBooks for a user found in the AuthorizedUsers collection.

Any of the QuickBooks Integrator classs can connect to the QBConnector using the QBConnectionString property of any of the classs. For instance, an example using the Invoice class follows:

  Invoice.QBConnectionString = "URL='http://www.foo.com:2080'" User='Foo' Password='Bar'";

Using SSL along with a digital certificate greatly increases the security of the Remote Connector. SSL will encrypt all data transmitted across the network, ensuring that only the Connector can read incoming requests, and that only the requesting client can read the QuickBooks responses. This prevents unauthorized parties from accessing your QuickBooks data. You should use a full digital certificate on the server (Connector) side, and this will contain a public key and a private key. This version of your certificate should be kept private. You may export a version of the certificate containing the public key only, and distribute this to all clients that need to communicate with the Connector.

To use this functionality, set the SSLCert with a valid certificate and then change the SSLStartMode to sslImplicit. Now all clients must post to the QBConnector using HTTPS. eg:

  Invoice.QBConnectionString = "URL='https://www.foo.com:2080' User='Foo' Password='Bar'"; // https instead of http

The client (in these examples Invoice) has an SSLServerAuthentication event that will fire when the server presents its certificate. If the public key presented by the QBConnector is trusted by the system, the Accept parameter will be True. If it is not trusted by the system (Accept is False), you should inspect the certificate and if valid, override by setting Accept to True.

Property List


The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

AuthorizedUserCountThe number of records in the Authorized arrays.
AuthorizedAuthModeThis property defines how the user is authorized.
AuthorizedUserPasswordA password associated with the User who is allowed to connect to the class.
AuthorizedUserQBConnectionStringAn aggregate consisting of various QuickBooks connection properties that are used to connect the authorized client to the QuickBooks application.
AuthorizedUserName of a user which is allowed to connect to the class.
ConnectedToQBOpens or closes a persistent connection to QuickBooks.
EnableSSLIndicates whether server starts in SSL-mode.
ListeningIf True, the class accepts incoming connections on LocalPort.
LocalHostThe name of the local host or user-assigned IP interface through which connections are initiated or accepted.
LocalPortThe TCP port in the local host where the class listens.
SSLAuthenticateClientsIf true, the server asks the client(s) for a certificate.
SSLCertEncodedThe certificate (PEM/base64 encoded).
SSLCertStoreThe name of the certificate store for the client certificate.
SSLCertStorePasswordIf the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.
SSLCertStoreTypeThe type of certificate store for this certificate.
SSLCertSubjectThe subject of the certificate used for client authentication.
TimeoutAn initial timeout value to be used by incoming connections.

Method List


The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

AddUserAdds a new user to the AuthorizedUsers collection.
ConfigSets or retrieves a configuration setting.
DoEventsProcesses events from the internal message queue.
ResetClears all properties to their default values.
ShutdownShutdown the server.

Event List


The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

AuthorizationFired when the client presents its credentials to the server.
ConnectedFired immediately after a connection completes (or fails).
ConnectionRequestFired when a request for connection comes from a remote host.
DisconnectedFired when a connection is closed.
ErrorInformation about errors during data delivery.
HeaderHTTP headers sent by the client.
RequestFired when a client sends a request to the class.
ResponseFired when the class sends a response to the client.
SSLClientAuthenticationFired when the client presents its credentials to the server.
SSLConnectionRequestFires when an SSL connection is requested.
SSLStatusShows the progress of the secure connection.
StatusShows the status of the server as clients connect and transactions are made.

Configuration Settings


The following is a list of configuration settings for the class with short descriptions. Click on the links for further details.

AuthFlagsAuth Flags to use when connecting to QuickBooks.
ConnectedToQBUsed to connect or disconnect from QuickBooks.
DefaultConnectionStringDefault connection string to use for users not in the AuthorizedUsers collection.
ReadOnly[i]Whether a user is restricted to read-only access.
UseInteractiveLogonWhether interactive or network logon is used when AuthMode is set to Windows.
BuildInfoInformation about the product's build.
CodePageThe system code page used for Unicode to Multibyte translations.
LicenseInfoInformation about the current license.
ProcessIdleEventsWhether the class uses its internal event loop to process events when the main thread is idle.
SelectWaitMillisThe length of time in milliseconds the class will wait when DoEvents is called if there are no events to process.
UseInternalSecurityAPITells the class whether or not to use the system security libraries or an internal implementation.

Copyright (c) 2021 /n software inc. - All rights reserved.
QuickBooks Integrator 2020 C++ Edition - Version 20.0 [Build 7941]