rttr::library Class Reference

The library class provides a cross platform way of explicit loading shared objects (.so on Unix based system and .DLL on windows). More...

#include <library.h>

Public Member Functions

 library (string_view file_name, string_view version=string_view())
 Constructs a library instance that will load the given library file_name and an optional version number version. More...
 
 library (const library &)=delete
 
 ~library ()
 Destroys the library instance. More...
 
string_view get_error_string () const noexcept
 Returns a text string with the description of the last error that occurred. More...
 
string_view get_file_name () const noexcept
 When the library was not yet loaded, the file name given in the constructor will be returned. More...
 
array_range< methodget_global_methods () const noexcept
 A range of all registered global methods in this library. More...
 
array_range< propertyget_global_properties () const noexcept
 A range of all registered global properties in this library. More...
 
array_range< typeget_types () const noexcept
 A range of all registered type in this library. More...
 
bool is_loaded () const noexcept
 Returns true if the library is loaded; otherwise returns false. More...
 
bool load ()
 Loads the library and returns true; otherwise `false. More...
 
libraryoperator= (const library &)=delete
 
bool unload ()
 Unloads the library. More...
 

Detailed Description

The library class provides a cross platform way of explicit loading shared objects (.so on Unix based system and .DLL on windows).

With a call to load() the library will be loaded and with unload() unloaded. The explicit call to unload() is not necessary. An internal ref count will trigger the unload automatically on application exit. So you are free the let the library instance go out of scope after loading, the type data will still be available.

After loading the library, the types of the plugin will be registered to the type system of RTTR. Use therefore the macro: RTTR_PLUGIN_REGISTRATION. The types or global properties or methods can be retrieved directly from the library class via getters.

Because the types are registered via RTTR, it is not necessary to additionally mark your types for export (e.g. using __declspec( dllexport ) on windows). Furthermore, with using RTTR, it is possible to export overloaded methods (same name but different signature).

Copying and Assignment

A library object cannot be copied or assigned.

Typical Usage

A typical usage example is the following: Some cpp file in your plugin called: "MyPlugin":

#include <rttr/registration>
struct Foo
{
void set_value(int v) { value = v; }
int get_value() const { return value; }
int value = 0;
};
{
.constructor<>()
.property("value", &Foo::set_value, &Foo::get_value);
}

Now in your application, which loads the plugin:

library lib("MyPlugin"); // file suffix is not needed, will be automatically appended
lib.load();
auto t = type::get_by_name("Foo");
std::cout << t.get_name() << std::endl; // prints "Foo"
variant var = t.create();
auto value = t.set_property_value("value", var, 12);
std::cout << t.get_property_value("value", var).to_string() << std::endl; // prints "12"

Constructor & Destructor Documentation

rttr::library::library ( string_view  file_name,
string_view  version = string_view() 
)

Constructs a library instance that will load the given library file_name and an optional version number version.

The file name is expected to be encoded in UTF-8 format.

It is recommend to omit the file suffix, the library class will automatically look for a file with the native library suffix/prefix ( e.g. lib, .so on Unix, .dylib on macOS and iOS, and .dll on Windows)

rttr::library::~library ( )

Destroys the library instance.

Remarks
This will not unload the library. However, on application exit, the library will be unloaded automatically.
See also
unload()
rttr::library::library ( const library )
delete

Member Function Documentation

string_view rttr::library::get_error_string ( ) const
noexcept

Returns a text string with the description of the last error that occurred.

The error string will be only set when the loading or unloading fails.

Returns
An error string. Empty when no error occurred.
See also
load(), unload()
string_view rttr::library::get_file_name ( ) const
noexcept

When the library was not yet loaded, the file name given in the constructor will be returned.

After a successful call to load(), get_file_name() returns the fully-qualified file name of the library, including the absolute path to the library if one was given in the constructor. e.g.

library lib("MyPlugin"); // loading a windows DLL relative (actual name is MyPlugin.dll)
lib.load();
lib.get_file_name(); // returns "MyPlugin.dll"
Returns
true when the library is loaded; otherwise false.
See also
load(), unload()
array_range<method> rttr::library::get_global_methods ( ) const
noexcept

A range of all registered global methods in this library.

Returns
A range of all loaded methods. Or empty if no methods were loaded.
See also
method
array_range<property> rttr::library::get_global_properties ( ) const
noexcept

A range of all registered global properties in this library.

Returns
A range of all loaded properties. Or empty if no properties were loaded.
See also
property
array_range<type> rttr::library::get_types ( ) const
noexcept

A range of all registered type in this library.

Returns
A range of all loaded types. Or empty if no types were loaded.
See also
type
bool rttr::library::is_loaded ( ) const
noexcept

Returns true if the library is loaded; otherwise returns false.

Returns
true when the library is loaded; otherwise false.
See also
load(), unload()
bool rttr::library::load ( )

Loads the library and returns true; otherwise `false.

` When the library could not be loaded, check the error string.

Returns
true when the library was successfully loaded; otherwise false.
See also
unload(), get_error_string()
library& rttr::library::operator= ( const library )
delete
bool rttr::library::unload ( )

Unloads the library.

On application exit this happens automatically, so usually you don't need to call this function. When the same library is loaded multiple times, this call will not succeed before every library instance was unloaded.

Remarks
When you unload the library, make sure you don't hold any data (methods, properties or variants etc...) anymore, which was created by this library. Otherwise undefined behavior may occur (crash!).
Returns
true when the library was successfully unloaded, otherwise false.
See also
load(), get_error_string()

The documentation for this class was generated from the following file: