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/strings/string_piece.h"
  15 #include "build/build_config.h"
  16
  17 #if defined(OS_WIN)
  18 #include <windows.h>
  19 #elif defined(OS_MACOSX)
  20 #import <CoreFoundation/CoreFoundation.h>
  21 #endif  // OS_*
  22
  23 namespace base {
  24
  25 class FilePath;
  26
  27 #if defined(OS_WIN)
  28 using NativeLibrary = HMODULE;
  29 #elif defined(OS_MACOSX)
  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   CFBundleRefNum bundle_resource_ref;
  42   NativeLibraryObjCStatus objc_status;
  43   union {
  44     CFBundleRef bundle;
  45     void* dylib;
  46   };
  47 };
  48 using NativeLibrary = NativeLibraryStruct*;
  49 #elif defined(OS_POSIX) || defined(OS_FUCHSIA)
  50 using NativeLibrary = void*;
  51 #endif  // OS_*
  52
  53 struct BASE_EXPORT NativeLibraryLoadError {
  54 #if defined(OS_WIN)
  55   NativeLibraryLoadError() : code(0) {}
  56 #endif  // OS_WIN
  57
  58   // Returns a string representation of the load error.
  59   std::string ToString() const;
  60
  61 #if defined(OS_WIN)
  62   DWORD code;
  63 #elif defined(OS_POSIX) || defined(OS_FUCHSIA)
  64   std::string message;
  65 #endif  // OS_WIN
  66 };
  67
  68 struct BASE_EXPORT NativeLibraryOptions {
  69   NativeLibraryOptions() = default;
  70   NativeLibraryOptions(const NativeLibraryOptions& options) = default;
  71
  72   // If |true|, a loaded library is required to prefer local symbol resolution
  73   // before considering global symbols. Note that this is already the default
  74   // behavior on most systems. Setting this to |false| does not guarantee the
  75   // inverse, i.e., it does not force a preference for global symbols over local
  76   // ones.
  77   bool prefer_own_symbols = false;
  78 };
  79
  80 // Loads a native library from disk.  Release it with UnloadNativeLibrary when
  81 // you're done.  Returns NULL on failure.
  82 // If |error| is not NULL, it may be filled in on load error.
  83 BASE_EXPORT NativeLibrary LoadNativeLibrary(const FilePath& library_path,
  84                                             NativeLibraryLoadError* error);
  85
  86 // Loads a native library from disk.  Release it with UnloadNativeLibrary when
  87 // you're done.  Returns NULL on failure.
  88 // If |error| is not NULL, it may be filled in on load error.
  89 BASE_EXPORT NativeLibrary LoadNativeLibraryWithOptions(
  90     const FilePath& library_path,
  91     const NativeLibraryOptions& options,
  92     NativeLibraryLoadError* error);
  93
  94 // Unloads a native library.
  95 BASE_EXPORT void UnloadNativeLibrary(NativeLibrary library);
  96
  97 // Gets a function pointer from a native library.
  98 BASE_EXPORT void* GetFunctionPointerFromNativeLibrary(NativeLibrary library,
  99                                                       StringPiece name);
 100
 101 // Returns the full platform-specific name for a native library. |name| must be
 102 // ASCII. This is also the default name for the output of a gn |shared_library|
 103 // target. See tools/gn/docs/reference.md#shared_library.
 104 // For example for "mylib", it returns:
 105 // - "mylib.dll" on Windows
 106 // - "libmylib.so" on Linux
 107 // - "libmylib.dylib" on Mac
 108 BASE_EXPORT std::string GetNativeLibraryName(StringPiece name);
 109
 110 // Returns the full platform-specific name for a gn |loadable_module| target.
 111 // See tools/gn/docs/reference.md#loadable_module
 112 // The returned name is the same as GetNativeLibraryName() on all platforms
 113 // except for Mac where for "mylib" it returns "mylib.so".
 114 BASE_EXPORT std::string GetLoadableModuleName(StringPiece name);
 115
 116 }  // namespace base
 117
 118 #endif  // BASE_NATIVE_LIBRARY_H_