Zen API
|
kStatus kPlugin_ConstructEx | ( | kPlugin * | plugin, |
const kChar * | path, | ||
kVersion | requiredPlatformVersion, | ||
kVersion * | platformVersion, | ||
kVersion | requiredAssemblyVersion, | ||
kVersion * | assemblyVersion, | ||
kAlloc | allocator | ||
) |
Constructs a kPlugin object, optionally performing version checks to ensure compatibility.
The requiredPlatformVersion argument is checked against the platform version that the plugin was built against. Any digits of the requiredPlatformVersion field that are set to 255 will not be checked. If all digits are 255 (or all zero), no check will be performed. Assuming the library can be loaded and queried for its version, the platformVersion argument will receive the actual platform version that the plugin was built against. This value can be used in error reporting logic if kERROR_VERSION is returned by this function. Note that platform builds are only expected to be binary-compatible after they have achieved release status, and only if the major, minor, and release digits all match. Accordingly, when performing platform version checks, it is strongly recommended to check at least the major, minor, and release version digits.
Similarly, the requiredAssemblyVersion argument is checked against the version of the plugin assembly. Any digits of the requiredAssemblyVersion field that are set to 255 will not be checked. If all digits are 255 (or all zero), no check will be performed. Assuming the library can be loaded and queried for its version, the assemblyVersion argument will receive the actual plugin assembly version. This value can be used in error reporting logic if kERROR_VERSION is returned by this function. Assembly version checking requires that plugins are built with at least platform version 6.2.6.28; if a required assembly version is specified and the plugin was built against an older platform version, loading will fail.
The following error codes will be returned in the event of specific failures: -kERROR_NOT_FOUND: Dynamic library missing or otherwise unloadable. -kERROR_INCOMPLETE: Dynamic load failed due to unresolved symbols. -kERROR_FORMAT: Required plugin method(s) not available. -kERROR_VERSION: Version mismatch (platform or assembly). -kERROR_CONFLICT: Assembly construction failure.
plugin | Destination for the constructed object handle. |
path | Path to the plugin library. |
requiredPlatformVersion | Required platform version (all-digits-zero to fully disable, or 255 per digit to disable individual digits). |
platformVersion | Actual platform version (optional, can be kNULL; receives 0.0.0.0 if unknown). |
requiredAssemblyVersion | Required plugin assembly version (all-digits-zero to fully disable, or 255 per digit to disable individual digits). |
assemblyVersion | Actual assembly version (optional, can be kNULL; receives 0.0.0.0 if unknown). |
allocator | Memory allocator (or kNULL for default). |