base/native_library.h

   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.
   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/strings/string_piece.h"
  16 #include "build/build_config.h"
  17
  18 #if defined(OS_WIN)
  19 #include <windows.h>
  20 #elif defined(OS_MACOSX)
  21 #import <CoreFoundation/CoreFoundation.h>
  22 #endif  // OS_*
  23
  24 namespace base {
  25
  26 #if defined(OS_WIN)
  27 using NativeLibrary = HMODULE;
  28 #elif defined(OS_MACOSX)
  29 enum NativeLibraryType {
  30   BUNDLE,
  31   DYNAMIC_LIB
  32 };
  33 enum NativeLibraryObjCStatus {
  34   OBJC_UNKNOWN,
  35   OBJC_PRESENT,
  36   OBJC_NOT_PRESENT,
  37 };
  38 struct NativeLibraryStruct {
  39   NativeLibraryType type;
  40   CFBundleRefNum bundle_resource_ref;
  41   NativeLibraryObjCStatus objc_status;
  42   union {
  43     CFBundleRef bundle;
  44     void* dylib;
  45   };
  46 };
  47 using NativeLibrary = NativeLibraryStruct*;
  48 #elif defined(OS_POSIX) || defined(OS_FUCHSIA)
  49 using NativeLibrary = void*;
  50 #endif  // OS_*
  51
  52 struct BASE_EXPORT NativeLibraryLoadError {
  53 #if defined(OS_WIN)
  54   NativeLibraryLoadError() : code(0) {}
  55 #endif  // OS_WIN
  56
  57   // Returns a string representation of the load error.
  58   std::string ToString() const;
  59
  60 #if defined(OS_WIN)
  61   DWORD code;
  62 #elif defined(OS_POSIX) || defined(OS_FUCHSIA)
  63   std::string message;
  64 #endif  // OS_WIN
  65 };
  66
  67 struct BASE_EXPORT NativeLibraryOptions {
  68   NativeLibraryOptions() = default;
  69   NativeLibraryOptions(const NativeLibraryOptions& options) = default;
  70
  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
  75   // ones.
  76   bool prefer_own_symbols = false;
  77 };
  78
  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);
  84
  85 #if defined(OS_WIN)
  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
  89 // thread.
  90 BASE_EXPORT NativeLibrary
  91 LoadSystemLibrary(FilePath::StringPieceType name,
  92                   NativeLibraryLoadError* error = nullptr);
  93
  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);
 102 #endif
 103
 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);
 111
 112 // Unloads a native library.
 113 BASE_EXPORT void UnloadNativeLibrary(NativeLibrary library);
 114
 115 // Gets a function pointer from a native library.
 116 BASE_EXPORT void* GetFunctionPointerFromNativeLibrary(NativeLibrary library,
 117                                                       StringPiece name);
 118
 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);
 127
 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);
 133
 134 }  // namespace base
 135
 136 #endif  // BASE_NATIVE_LIBRARY_H_