blob: 737f28c7019440c16044b7e698aa095631317666 [file] [log] [blame]
// Copyright (c) 2019, the Dart project authors. Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.
part of dart.ffi;
/// A dynamically loaded native library.
///
/// A dynamically loaded library is a mapping from symbols to memory addresses.
/// These memory addresses can be accessed through [lookup].
class DynamicLibrary {
/// Creates a dynamic library holding all global symbols.
///
/// Any symbol in a library currently loaded with global visibility
/// (including the executable itself) may be resolved through this library.
///
/// This feature is not available on Windows.
external factory DynamicLibrary.process();
/// Creates a dynamic library containing all the symbols of the running
/// executable.
external factory DynamicLibrary.executable();
/// Loads a library file and provides access to its symbols.
///
/// The [path] must refer to a native library file which can be successfully
/// loaded.
///
/// Calling this function multiple times with the same [path], even across
/// different isolates, only loads the library into the DartVM process once.
/// Multiple loads of the same library file produces [DynamicLibrary] objects
/// which are equal (`==`), but not [identical].
external factory DynamicLibrary.open(String path);
/// Looks up a symbol in the [DynamicLibrary] and returns its address in
/// memory.
///
/// Similar to the functionality of the
/// [dlsym(3)](https://man7.org/linux/man-pages/man3/dlsym.3.html) system
/// call.
///
/// The symbol must be provided by the dynamic library. To check whether
/// the library provides such symbol, use [providesSymbol].
external Pointer<T> lookup<T extends NativeType>(String symbolName);
/// Checks whether this dynamic library provides a symbol with the given
/// name.
@Since('2.14')
external bool providesSymbol(String symbolName);
/// Dynamic libraries are equal if they load the same library.
external bool operator ==(Object other);
/// The hash code for a [DynamicLibrary] only depends on the loaded library.
external int get hashCode;
/// The opaque handle to the dynamic library.
///
/// Similar to the return value of
/// [dlopen(3)](https://man7.org/linux/man-pages/man3/dlopen.3.html).
/// Can be used as arguments to other functions in the `dlopen` API
/// through FFI calls.
external Pointer<Void> get handle;
}
/// Method which must not be invoked dynamically.
extension DynamicLibraryExtension on DynamicLibrary {
/// Looks up a native function and returns it as a Dart function.
///
/// [T] is the C function signature, and [F] is the Dart function signature.
/// For example:
///
/// ```c
/// int32_t add(int32_t a, int32_t b) {
/// return a + b;
/// }
/// ```
///
/// ```dart
/// DynamicLibrary dylib;
/// final add = dylib.lookupFunction<Int32 Function(Int32, Int32),
/// int Function(int, int)>('add');
/// ```
external F lookupFunction<T extends Function, F extends Function>(
String symbolName,
{bool isLeaf: false});
}