carb::extras::loadLibrary¶

inline LibraryHandle carb::extras::loadLibrary(const char *libraryName, LibraryFlags flags = 0)¶

Attempts to load a named library into the calling process.

Remark: This attempts to dynamically load a named library into the calling process. If the library is already loaded, a handle to it is returned. If the module was not already loaded, it is dynamically loaded and a handle to it is returned. When a module is dynamically loaded into a process, its existence in the process is reference counted. A newly loaded library will be given a reference count of one. Each time the same dynamically library is loaded, its reference count is incremented. Each successful call to this function should therefore be balanced by a call to unloadLibrary().
Remark: Modules that were loaded as part of the process’s static dependencies list will be ‘pinned’ and their reference count will not be changed by attempting to load them. It is still safe to call unloadLibrary() on handles for those pinned libraries.

Parameters

libraryName – [in] The name of the library to attempt to load. This may be either a relative or absolute path name. This should be a UTF-8 encoded path. If the fLibFlagMakeFullLibName flag is used, the library name may omit any platform specific prefix or file extension. The appropriate platform specific name will be generated internally using createLibraryNameForModule().
flags – [in] Flags to control the behavior of the operation. This defaults to 0.

Returns

A handle to the library if it is successfully loaded into the process. This handle should be cleaned up by unloadLibrary() when it is no longer necessary.

Returns

A handle to the library if it was already loaded in the process. This handle should be cleaned up by unloadLibrary() when it is no longer necessary.

Returns

nullptr if the library could not be found or could not be loaded.