fillInterface

template<class T> bool fillInterface(carb::Version *v, void *buf)

A required function that a plugin author must provide to construct a requested version of an interface.

This function can be called at any time after carbOnPluginRegisterEx2 is called by the framework when the plugin is loaded. Generally this is called immediately for all interfaces for the version specified in their CARB_PLUGIN_INTERFACE declaration, and at later points when a different interface version is requested. The plugin will fail to link if this function is not provided for all of the interfaces specified in the use of the CARB_PLUGIN_IMPL_EX macro.

// Example
template <>
bool fillInterface<carb::stats::IStats>(carb::Version* v, void* iface)
{
    using namespace carb::stats;
    switch (v->major)
    {
        case IStats::getLatestInterfaceDesc().version.major:
            *v = IStats::getLatestInterfaceDesc().version;
            *static_cast<IStats*>(iface) = { addStat, removeStat, addValue, getValue, getCount };
            return true;

        default:
            return false;
    }
}

Note

This version of the function is required when using CARB_PLUGIN_IMPL_EX. When using CARB_PLUGIN_IMPL, fillInterface(InterfaceType&) is used instead.

Warning

This function must succeed (return true) with v unchanged when called with v equal to the version specified in CARB_PLUGIN_INTERFACE, otherwise the plugin will fail to register or load.

Warning

If the type T that you’re explicitly specializing is a complex type, make sure to provide a destroyInterface function to destruct the interface.

Template Parameters

T – The interface type handled by this function. The generic class template for any type T is declared but not implemented by the CARB_PLUGIN_IMPL_EX macro. This allows explicit specialization for the plugin author to provide the function for their types. For instance, if you are providing the function for carb::IObject, your function would be template <> bool fillInterface<carb::IObject>(carb::Version* v, void* iface).

Parameters

v – When called, the framework provides the version requested. The function must write the version constructed into this parameter before returning. The version constructed does not need to be the same as (or even semantically compatible with) the version requested, but if a semantically compatible interface to the requested version is available it should be provided.
buf – A memory buffer that is guaranteed to be at least as large as sizeof(T), allocated and owned by the framework. For the initial allocation of an interface, this buffer is zeroed memory. If T is a POD type, the memory can be cast to T* and filled in, or placement new can be used to construct your type. If T is a more complex type, provide a destroyInterface function to destruct the type.

Return values

true – to indicate that the type was constructed and v contains the version that was constructed, even if the version is different from the value that was in v when the function was called.
false – to indicate that the requested interface version could not be constructed.