 | Basics of IVI Driver Versioning |
Once a driver has been implemented, tested, and released, it should not be modified in ways that would break backwards compatibility with applications built against the released driver. Nimbus offers a Publish command that, when executed, locks down the driver such that it cannot be modified in ways that would make it incompatible with the released version. After publishing a driver via the Publish command, the driver interface definitions and other API elements can only be modified by explicitly versioning an interface via the Revise Interface command.
This topic explains how drivers are published after release and how published drivers are subsequently revised to accommodate new requirements.
Publishing an IVI DriverThe goal of IVI driver versioning is to enable end users to install a new version of a driver without invalidating existing applications built against against the previous version of the driver. Ideally, client applications should require no modification nor even a re-compile or re-link. This should be the case irrespective of the IDE in which the IVI driver is used. To accomplish this, a variety of rules must be obeyed once an IVI driver has been released (aka "published") to customers. These rules are summarized later in this section.
Nimbus offers a Publish command that helps enforce the rules for maintaining a driver that has been released to customers.
 Caution |
|---|
Before publishing a driver with the Publish command, be certain that the driver requires no further modification for release. Once the Publish command has been executed, the driver can only be modified using the Revise Interface command described below. There is "Unpublish" command. |
To publish an IVI driver
From Solution Explorer, right-click on the the Nimbus node, and choose Publish....
A confirmation dialog is presented to confirm the command.
When the command completes, the methods and properties appear in blue in the tree view, indicating that they are published and cannot be directly modified.
Rules for Maintain Backwards Compatibility with Released Drivers
- Do not add or remove methods or properties from an IVI-COM interface
The fundamental rule for versioning IVI-COM interfaces is simple: interfaces are immutable. This means that methods and properties cannot be added or removed from an IVI-COM driver interface after the interface has been published. Doing so would break COM's binary compatibility model, and client applications will fail to compile or to run after installing an improperly versioned IVI-COM driver. Sometimes these runtime failures can be subtle indeed. Thus, it is critical that proper COM versioning techniques be used when adding or removing interfaces from an IVI-COM driver.
For a discussion of COM versioning, see the topic Understanding COM Versioning.
- Do not change the signature of a method or property
As discussed in Rule 1, COM intefaces are immutable. It follows that the method and property definitions within an inteface are also immutable. This means that once you have published a driver, you cannot change the signature of any methods or properties in any interface. The signature includes the method or property name, return type, as well as the type and number of parameters. You cannot add or remove parameters, nor can you change the data type of any of the parameters or the return type.
- Do not change the name or value of an IVI-C attribute identifier
IVI-C attributes are implemented as #define statements in the IVI-C header file (<prefix>.h). Neither the symbolic name nor the numeric value for the attribute can change after the driver has been published.
- Do not change the name or numeric value of enum members
Enums in IVI-COM are part of the signature of the method (or property) in which they are used. Thus, with respect to IVI-COM, this rule is really just a specific case of Rule 2 above. For IVI-C, enum values are represented as #define statements in the IVI-C header file (<prefix>.h).
- Do not change the name or numeric value of error codes
Error codes in both IVI-COM and IVI-C have symbolic names and error code values. Only the specific error field (bits 11-0 of the error value) portion of the error code value may be edited by the driver developer. The other portions of the error code are prescribed by IVI-3.1: Driver Architecture Specification. Since client applications will have direct references to the error code names and values, it is important not to change these either of these after publishing a driver.
Revising a Published IVI Driver InterfaceOnce an IVI driver interface has been published via the Publish command, the only way to make changes to the driver hierarchy is by revising the interface using the Revise Interface command. Nimbus offers two techniques for revising an interface, and it's important to understand the implications of choosing one technique over the other. See the topic Understanding COM Versioning for a discussion of the two IVI driver versioning techniques offered by Nimbus.
To revise a published IVI driver interface
From Solution Explorer, double-click the Driver Designer node under the Nimbus node.
The Driver Designer opens as a tabbed document window. Select the IVI-COM tab.
Click the Hierarchical button beneath the tree view on the left side of the IVI-COM Designer.
Locate the interface reference property for the interface you wish to version. If working from the flat view, locate the interface directly.
Right-click and choose Revise Interface. The Revise Interface Dialog appears. See the help topic for the Revise Interface Dialog for details on the options available.