base/native_library.h

   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)
  56   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_