The QBCONNECTOR component is a utility that allows you to connect your QuickBooks Integrator applications to remote QuickBooks instances.
The QBConnector component is a lightweight web server which listens for HTTP requests originating from the QuickBooks Integrator components. Each request sent to the QBConnector by a QuickBooks Integrator component 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 component is easy. Simply set Listening to True, and the component 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 component 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.
Any of the QuickBooks Integrator components can connect to the QBConnector using the QBConnectionString property of any of the components.
For instance, an example using the Invoice component 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.
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.
The following is the full list of the properties of the component with short descriptions. Click on the links for further details.
|AuthorizedUsers||A list of clients allowed to connect to the server.|
|ConnectedToQB||Opens or closes a persistent connection to QuickBooks.|
|EnableSSL||Indicates whether server starts in SSL-mode.|
|Listening||If True, the component accepts incoming connections on LocalPort.|
|LocalHost||The name of the local host or user-assigned IP interface through which connections are initiated or accepted.|
|LocalPort||The TCP port in the local host where the component listens.|
|SSLAuthenticateClients||If true, the server asks the client(s) for a certificate.|
|SSLCert||The certificate to be used during SSL negotiation.|
|Timeout||An initial timeout value to be used by incoming connections.|
The following is the full list of the methods of the component with short descriptions. Click on the links for further details.
|AddUser||Adds a new user to the AuthorizedUsers collection.|
|Config||Sets or retrieves a configuration setting.|
|DoEvents||Processes events from the internal message queue.|
|Reset||Clears all properties to their default values.|
|Shutdown||Shutdown the server.|
The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.
|Authorization||Fired when the client presents its credentials to the server.|
|Connected||Fired immediately after a connection completes (or fails).|
|ConnectionRequest||Fired when a request for connection comes from a remote host.|
|Disconnected||Fired when a connection is closed.|
|Error||Information about errors during data delivery.|
|Header||HTTP headers sent by the client.|
|Request||Fired when a client sends a request to the component.|
|Response||Fired when the component sends a response to the client.|
|SSLClientAuthentication||Fired when the client presents its credentials to the server.|
|SSLConnectionRequest||Fires when an SSL connection is requested.|
|SSLStatus||Shows the progress of the secure connection.|
|Status||Shows the status of the server as clients connect and transactions are made.|
The following is a list of configuration settings for the component with short descriptions. Click on the links for further details.
|AuthFlags||Auth Flags to use when connecting to QuickBooks.|
|ConnectedToQB||Used to connect or disconnect from QuickBooks.|
|DefaultConnectionString||Default connection string to use for users not in the AuthorizedUsers collection.|
|ReadOnly[i]||Whether a user is restricted to read-only access.|
|UseInteractiveLogon||Whether interactive or network logon is used when AuthMode is set to Windows.|
|BuildInfo||Information about the product's build.|
|GUIAvailable||Tells the component whether or not a message loop is available for processing events.|
|LicenseInfo||Information about the current license.|
|UseInternalSecurityAPI||Tells the component whether or not to use the system security libraries or an internal implementation.|