4.4.1.4 Interface Versions

Unlike COM, SCF supports interface versions. That is, a shared class could implement version 0.3.6 of given interface, and if client requests that interface of a version lower or equal than 0.3.6, a correct interface pointer is returned. For this to work you need to define inside each interface header file a specialization of the scfInterface<> template class for each interface. This specialization must provide the interface's version number as the result of its GetVersion() method. To correctly support different versions of interfaces you should follow these guidelines:

• Do not insert new methods into existing interfaces. Instead, you should append them after last defined method.
• If your change made the interface invalid for clients that expect older versions of interfaces (for example, you broke the previous rule), increase the major version number, and set minor and micro versions to zero.
• If your changes are relatively minor, but you do a major release, increase the minor version number and drop the micro version to zero.
• If you are in the development process, and did a minor change to the interface, increase the micro version.

The possible range for major and minor version numbers is 0..255, and the range for micro version number is 0..65535.

When you query an interface, you should always tell it what interface version are you looking for. If a module cannot provide an interface compatible with the requested version, then QueryInterface() will return `NULL' (same as if interface wasn't available at all). You can use scfCompatibleVersion() to check whether the requested version is compatible with interface version. In fact, the SCF_IMPLEMENTS_INTERFACE() and SCF_IMPLEMENTS_EMBEDDED_INTERFACE() macros employ this function automatically.

Since specializing the scfInterface<> template for each interface is an onerous task, you can instead automate the task via use of the SCF_VERSION() macro.

SCF_VERSION(iMyGraphics3D, 0, 0, 1);

struct iMyGraphics3D : public iBase
{
  ...
};

If you are placing your interfaces in your project's own namespace, then you must invoke the SCF_VERSION() macro outside your namespace. For instance:

namespace MyProject
{
  struct iMyGraphics3D : public iBase
  {
    ...
  };
}

SCF_VERSION(MyProject::iMyGraphics3D, 0, 0, 1);

This document was generated using texi2html 1.76.