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 13 #include "base/base_export.h" 14 #include "base/files/file_path.h" 15 #include "base/memory/raw_ptr_exclusion.h" 16 #include "base/strings/string_piece.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 enum NativeLibraryObjCStatus { 35 OBJC_UNKNOWN, 36 OBJC_PRESENT, 37 OBJC_NOT_PRESENT, 38 }; 39 struct NativeLibraryStruct { 40 NativeLibraryType type; 41 NativeLibraryObjCStatus objc_status; 42 union { 43 CFBundleRef bundle; 44 //// This field is not a raw_ptr<> because it was filtered by the rewriter 45 // for: #union 46 RAW_PTR_EXCLUSION void* dylib; 47 }; 48 }; 49 using NativeLibrary = NativeLibraryStruct*; 50 #elif BUILDFLAG(IS_POSIX) || BUILDFLAG(IS_FUCHSIA) 51 using NativeLibrary = void*; 52 #endif // OS_* 53 54 struct BASE_EXPORT NativeLibraryLoadError { 55 #if BUILDFLAG(IS_WIN) NativeLibraryLoadErrorNativeLibraryLoadError56 NativeLibraryLoadError() : code(0) {} 57 #endif // BUILDFLAG(IS_WIN) 58 59 // Returns a string representation of the load error. 60 std::string ToString() const; 61 62 #if BUILDFLAG(IS_WIN) 63 DWORD code; 64 #elif BUILDFLAG(IS_POSIX) || BUILDFLAG(IS_FUCHSIA) 65 std::string message; 66 #endif // BUILDFLAG(IS_WIN) 67 }; 68 69 struct BASE_EXPORT NativeLibraryOptions { 70 // If |true|, a loaded library is required to prefer local symbol resolution 71 // before considering global symbols. Note that this is already the default 72 // behavior on most systems. Setting this to |false| does not guarantee the 73 // inverse, i.e., it does not force a preference for global symbols over local 74 // ones. 75 bool prefer_own_symbols = false; 76 }; 77 78 // Loads a native library from disk. Release it with UnloadNativeLibrary when 79 // you're done. Returns NULL on failure. 80 // If |error| is not NULL, it may be filled in on load error. 81 BASE_EXPORT NativeLibrary LoadNativeLibrary(const FilePath& library_path, 82 NativeLibraryLoadError* error); 83 84 #if BUILDFLAG(IS_WIN) 85 // Loads a native library from the system directory using the appropriate flags. 86 // The function first checks to see if the library is already loaded and will 87 // get a handle if so. This method results in a lock that may block the calling 88 // thread. 89 BASE_EXPORT NativeLibrary 90 LoadSystemLibrary(FilePath::StringPieceType name, 91 NativeLibraryLoadError* error = nullptr); 92 93 // Gets the module handle for the specified system library and pins it to 94 // ensure it never gets unloaded. If the module is not loaded, it will first 95 // call LoadSystemLibrary to load it. If the module cannot be pinned, this 96 // method returns null and includes the error. This method results in a lock 97 // that may block the calling thread. 98 BASE_EXPORT NativeLibrary 99 PinSystemLibrary(FilePath::StringPieceType name, 100 NativeLibraryLoadError* error = nullptr); 101 #endif 102 103 // Loads a native library from disk. Release it with UnloadNativeLibrary when 104 // you're done. Returns NULL on failure. 105 // If |error| is not NULL, it may be filled in on load error. 106 BASE_EXPORT NativeLibrary LoadNativeLibraryWithOptions( 107 const FilePath& library_path, 108 const NativeLibraryOptions& options, 109 NativeLibraryLoadError* error); 110 111 // Unloads a native library. 112 BASE_EXPORT void UnloadNativeLibrary(NativeLibrary library); 113 114 // Gets a function pointer from a native library. 115 BASE_EXPORT void* GetFunctionPointerFromNativeLibrary(NativeLibrary library, 116 const char* name); 117 118 // Returns the full platform-specific name for a native library. |name| must be 119 // ASCII. This is also the default name for the output of a gn |shared_library| 120 // target. See tools/gn/docs/reference.md#shared_library. 121 // For example for "mylib", it returns: 122 // - "mylib.dll" on Windows 123 // - "libmylib.so" on Linux 124 // - "libmylib.dylib" on Mac 125 BASE_EXPORT std::string GetNativeLibraryName(StringPiece name); 126 127 // Returns the full platform-specific name for a gn |loadable_module| target. 128 // See tools/gn/docs/reference.md#loadable_module 129 // The returned name is the same as GetNativeLibraryName() on all platforms 130 // except for Mac where for "mylib" it returns "mylib.so". 131 BASE_EXPORT std::string GetLoadableModuleName(StringPiece name); 132 133 } // namespace base 134 135 #endif // BASE_NATIVE_LIBRARY_H_ 136