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.
The goal of IVI driver versioning is to enable end users to install a new version of a driver without invalidating existing applications built 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.
From Solution Explorer, right-click on 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 Maintaining 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.
Do not change the signature of a method or property
As discussed in Rule 1, COM interfaces are immutable. It follows that the method and property definitions within an interface 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 either of these after publishing a driver.
Once 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.
