1 // Copyright 2011 The Chromium Authors 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef BASE_NATIVE_LIBRARY_H_ 6 #define BASE_NATIVE_LIBRARY_H_ 7 8 // This file defines a cross-platform "NativeLibrary" type which represents 9 // a loadable module. 10 11 #include <string> 12 #include <string_view> 13 14 #include "base/base_export.h" 15 #include "base/files/file_path.h" 16 #include "base/memory/raw_ptr_exclusion.h" 17 #include "build/build_config.h" 18 19 #if BUILDFLAG(IS_WIN) 20 #include <windows.h> 21 #elif BUILDFLAG(IS_APPLE) 22 #import <CoreFoundation/CoreFoundation.h> 23 #endif // OS_* 24 25 namespace base { 26 27 #if BUILDFLAG(IS_WIN) 28 using NativeLibrary = HMODULE; 29 #elif BUILDFLAG(IS_APPLE) 30 enum NativeLibraryType { 31 BUNDLE, 32 DYNAMIC_LIB 33 }; 34 struct NativeLibraryStruct { 35 NativeLibraryType type; 36 union { 37 CFBundleRef bundle; 38 //// This field is not a raw_ptr<> because it was filtered by the rewriter 39 // for: #union 40 RAW_PTR_EXCLUSION void* dylib; 41 }; 42 }; 43 using NativeLibrary = NativeLibraryStruct*; 44 #elif BUILDFLAG(IS_POSIX) || BUILDFLAG(IS_FUCHSIA) 45 using NativeLibrary = void*; 46 #endif // OS_* 47 48 struct BASE_EXPORT NativeLibraryLoadError { 49 #if BUILDFLAG(IS_WIN) NativeLibraryLoadErrorNativeLibraryLoadError50 NativeLibraryLoadError() : code(0) {} 51 #endif // BUILDFLAG(IS_WIN) 52 53 // Returns a string representation of the load error. 54 std::string ToString() const; 55 56 #if BUILDFLAG(IS_WIN) 57 DWORD code; 58 #elif BUILDFLAG(IS_POSIX) || BUILDFLAG(IS_FUCHSIA) 59 std::string message; 60 #endif // BUILDFLAG(IS_WIN) 61 }; 62 63 struct BASE_EXPORT NativeLibraryOptions { 64 // If |true|, a loaded library is required to prefer local symbol resolution 65 // before considering global symbols. Note that this is already the default 66 // behavior on most systems. Setting this to |false| does not guarantee the 67 // inverse, i.e., it does not force a preference for global symbols over local 68 // ones. 69 bool prefer_own_symbols = false; 70 }; 71 72 // Loads a native library from disk. Release it with UnloadNativeLibrary when 73 // you're done. Returns NULL on failure. 74 // If |error| is not NULL, it may be filled in on load error. 75 BASE_EXPORT NativeLibrary LoadNativeLibrary(const FilePath& library_path, 76 NativeLibraryLoadError* error); 77 78 #if BUILDFLAG(IS_WIN) 79 // Loads a native library from the system directory using the appropriate flags. 80 // The function first checks to see if the library is already loaded and will 81 // get a handle if so. This method results in a lock that may block the calling 82 // thread. 83 BASE_EXPORT NativeLibrary 84 LoadSystemLibrary(FilePath::StringPieceType name, 85 NativeLibraryLoadError* error = nullptr); 86 87 // Gets the module handle for the specified system library and pins it to 88 // ensure it never gets unloaded. If the module is not loaded, it will first 89 // call LoadSystemLibrary to load it. If the module cannot be pinned, this 90 // method returns null and includes the error. This method results in a lock 91 // that may block the calling thread. 92 BASE_EXPORT NativeLibrary 93 PinSystemLibrary(FilePath::StringPieceType name, 94 NativeLibraryLoadError* error = nullptr); 95 #endif 96 97 // Loads a native library from disk. Release it with UnloadNativeLibrary when 98 // you're done. Returns NULL on failure. 99 // If |error| is not NULL, it may be filled in on load error. 100 BASE_EXPORT NativeLibrary LoadNativeLibraryWithOptions( 101 const FilePath& library_path, 102 const NativeLibraryOptions& options, 103 NativeLibraryLoadError* error); 104 105 // Unloads a native library. 106 BASE_EXPORT void UnloadNativeLibrary(NativeLibrary library); 107 108 // Gets a function pointer from a native library. 109 BASE_EXPORT void* GetFunctionPointerFromNativeLibrary(NativeLibrary library, 110 const char* name); 111 112 // Returns the full platform-specific name for a native library. |name| must be 113 // ASCII. This is also the default name for the output of a gn |shared_library| 114 // target. See tools/gn/docs/reference.md#shared_library. 115 // For example for "mylib", it returns: 116 // - "mylib.dll" on Windows 117 // - "libmylib.so" on Linux 118 // - "libmylib.dylib" on Mac 119 BASE_EXPORT std::string GetNativeLibraryName(std::string_view name); 120 121 // Returns the full platform-specific name for a gn |loadable_module| target. 122 // See tools/gn/docs/reference.md#loadable_module 123 // The returned name is the same as GetNativeLibraryName() on all platforms 124 // except for Mac where for "mylib" it returns "mylib.so". 125 BASE_EXPORT std::string GetLoadableModuleName(std::string_view name); 126 127 } // namespace base 128 129 #endif // BASE_NATIVE_LIBRARY_H_ 130