1 // Copyright (c) 2011 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 #ifndef BASE_NATIVE_LIBRARY_H_
6 #define BASE_NATIVE_LIBRARY_H_
8 // This file defines a cross-platform "NativeLibrary" type which represents
13 #include "base/base_export.h"
14 #include "base/files/file_path.h"
15 #include "base/strings/string_piece.h"
16 #include "build/build_config.h"
20 #elif defined(OS_APPLE)
21 #import <CoreFoundation/CoreFoundation.h>
27 using NativeLibrary = HMODULE;
28 #elif defined(OS_APPLE)
29 enum NativeLibraryType {
33 enum NativeLibraryObjCStatus {
38 struct NativeLibraryStruct {
39 NativeLibraryType type;
40 CFBundleRefNum bundle_resource_ref;
41 NativeLibraryObjCStatus objc_status;
47 using NativeLibrary = NativeLibraryStruct*;
48 #elif defined(OS_POSIX) || defined(OS_FUCHSIA)
49 using NativeLibrary = void*;
52 struct BASE_EXPORT NativeLibraryLoadError {
54 NativeLibraryLoadError() : code(0) {}
57 // Returns a string representation of the load error.
58 std::string ToString() const;
62 #elif defined(OS_POSIX) || defined(OS_FUCHSIA)
67 struct BASE_EXPORT NativeLibraryOptions {
68 NativeLibraryOptions() = default;
69 NativeLibraryOptions(const NativeLibraryOptions& options) = default;
71 // If |true|, a loaded library is required to prefer local symbol resolution
72 // before considering global symbols. Note that this is already the default
73 // behavior on most systems. Setting this to |false| does not guarantee the
74 // inverse, i.e., it does not force a preference for global symbols over local
76 bool prefer_own_symbols = false;
79 // Loads a native library from disk. Release it with UnloadNativeLibrary when
80 // you're done. Returns NULL on failure.
81 // If |error| is not NULL, it may be filled in on load error.
82 BASE_EXPORT NativeLibrary LoadNativeLibrary(const FilePath& library_path,
83 NativeLibraryLoadError* error);
86 // Loads a native library from the system directory using the appropriate flags.
87 // The function first checks to see if the library is already loaded and will
88 // get a handle if so. This method results in a lock that may block the calling
90 BASE_EXPORT NativeLibrary
91 LoadSystemLibrary(FilePath::StringPieceType name,
92 NativeLibraryLoadError* error = nullptr);
94 // Gets the module handle for the specified system library and pins it to
95 // ensure it never gets unloaded. If the module is not loaded, it will first
96 // call LoadSystemLibrary to load it. If the module cannot be pinned, this
97 // method returns null and includes the error. This method results in a lock
98 // that may block the calling thread.
99 BASE_EXPORT NativeLibrary
100 PinSystemLibrary(FilePath::StringPieceType name,
101 NativeLibraryLoadError* error = nullptr);
104 // Loads a native library from disk. Release it with UnloadNativeLibrary when
105 // you're done. Returns NULL on failure.
106 // If |error| is not NULL, it may be filled in on load error.
107 BASE_EXPORT NativeLibrary LoadNativeLibraryWithOptions(
108 const FilePath& library_path,
109 const NativeLibraryOptions& options,
110 NativeLibraryLoadError* error);
112 // Unloads a native library.
113 BASE_EXPORT void UnloadNativeLibrary(NativeLibrary library);
115 // Gets a function pointer from a native library.
116 BASE_EXPORT void* GetFunctionPointerFromNativeLibrary(NativeLibrary library,
119 // Returns the full platform-specific name for a native library. |name| must be
120 // ASCII. This is also the default name for the output of a gn |shared_library|
121 // target. See tools/gn/docs/reference.md#shared_library.
122 // For example for "mylib", it returns:
123 // - "mylib.dll" on Windows
124 // - "libmylib.so" on Linux
125 // - "libmylib.dylib" on Mac
126 BASE_EXPORT std::string GetNativeLibraryName(StringPiece name);
128 // Returns the full platform-specific name for a gn |loadable_module| target.
129 // See tools/gn/docs/reference.md#loadable_module
130 // The returned name is the same as GetNativeLibraryName() on all platforms
131 // except for Mac where for "mylib" it returns "mylib.so".
132 BASE_EXPORT std::string GetLoadableModuleName(StringPiece name);
136 #endif // BASE_NATIVE_LIBRARY_H_