api_binding.h 6.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184
  1. // Copyright 2016 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. #ifndef EXTENSIONS_RENDERER_BINDINGS_API_BINDING_H_
  5. #define EXTENSIONS_RENDERER_BINDINGS_API_BINDING_H_
  6. #include <map>
  7. #include <memory>
  8. #include <string>
  9. #include "base/callback.h"
  10. #include "base/containers/flat_set.h"
  11. #include "base/memory/weak_ptr.h"
  12. #include "base/supports_user_data.h"
  13. #include "extensions/renderer/bindings/argument_spec.h"
  14. #include "v8/include/v8.h"
  15. namespace base {
  16. class ListValue;
  17. }
  18. namespace gin {
  19. class Arguments;
  20. }
  21. namespace extensions {
  22. class APIBindingHooks;
  23. class APIEventHandler;
  24. class APIRequestHandler;
  25. class APISignature;
  26. class APITypeReferenceMap;
  27. class BindingAccessChecker;
  28. namespace binding {
  29. enum class RequestThread;
  30. }
  31. // A class that vends v8::Objects for extension APIs. These APIs have function
  32. // interceptors for all exposed methods, which call back into the APIBinding.
  33. // The APIBinding then matches the calling arguments against an expected method
  34. // signature, throwing an error if they don't match.
  35. // There should only need to be a single APIBinding object for each API, and
  36. // each can vend multiple v8::Objects for different contexts.
  37. // This object is designed to be one-per-isolate, but used across separate
  38. // contexts.
  39. class APIBinding {
  40. public:
  41. using CreateCustomType = base::RepeatingCallback<v8::Local<v8::Object>(
  42. v8::Isolate* isolate,
  43. const std::string& type_name,
  44. const std::string& property_name,
  45. const base::ListValue* property_values)>;
  46. // Called when a request is handled without notifying the browser.
  47. using OnSilentRequest = base::RepeatingCallback<void(
  48. v8::Local<v8::Context>,
  49. const std::string& name,
  50. const std::vector<v8::Local<v8::Value>>& arguments)>;
  51. // The callback type for handling an API call.
  52. using HandlerCallback = base::RepeatingCallback<void(gin::Arguments*)>;
  53. // The APITypeReferenceMap is required to outlive this object.
  54. // |function_definitions|, |type_definitions| and |event_definitions|
  55. // may be null if the API does not specify any of that category.
  56. APIBinding(const std::string& name,
  57. const base::ListValue* function_definitions,
  58. const base::ListValue* type_definitions,
  59. const base::ListValue* event_definitions,
  60. const base::DictionaryValue* property_definitions,
  61. CreateCustomType create_custom_type,
  62. OnSilentRequest on_silent_request,
  63. std::unique_ptr<APIBindingHooks> binding_hooks,
  64. APITypeReferenceMap* type_refs,
  65. APIRequestHandler* request_handler,
  66. APIEventHandler* event_handler,
  67. BindingAccessChecker* access_checker);
  68. APIBinding(const APIBinding&) = delete;
  69. APIBinding& operator=(const APIBinding&) = delete;
  70. ~APIBinding();
  71. // Returns a new v8::Object for the API this APIBinding represents.
  72. v8::Local<v8::Object> CreateInstance(v8::Local<v8::Context> context);
  73. APIBindingHooks* hooks() { return binding_hooks_.get(); }
  74. // Global bool to allow for testing of promise support.
  75. // TODO(tjudkins): Replace this with a runtime determined condition gated on
  76. // MV3.
  77. static bool enable_promise_support_for_testing;
  78. private:
  79. // Initializes the object_template_ for this API. Called lazily when the
  80. // first instance is created.
  81. void InitializeTemplate(v8::Isolate* isolate);
  82. // Decorates |object_template| with the properties specified by |properties|.
  83. // |is_root| is used to determine whether to add the properties to
  84. // |root_properties_|.
  85. void DecorateTemplateWithProperties(
  86. v8::Isolate* isolate,
  87. v8::Local<v8::ObjectTemplate> object_template,
  88. const base::DictionaryValue& properties,
  89. bool is_root);
  90. // Handler for getting the v8::Object associated with an event on the API.
  91. static void GetEventObject(v8::Local<v8::Name>,
  92. const v8::PropertyCallbackInfo<v8::Value>& info);
  93. // Handler for getting the v8::Object associated with a custom property on the
  94. // API.
  95. static void GetCustomPropertyObject(
  96. v8::Local<v8::Name> property,
  97. const v8::PropertyCallbackInfo<v8::Value>& info);
  98. // Handles calling of an API method with the given |name| on the given
  99. // |thread| and matches the arguments against |signature|.
  100. void HandleCall(const std::string& name,
  101. const APISignature* signature,
  102. gin::Arguments* args);
  103. // The root name of the API, e.g. "tabs" for chrome.tabs.
  104. std::string api_name_;
  105. // A map from method name to method data.
  106. struct MethodData;
  107. std::map<std::string, std::unique_ptr<MethodData>> methods_;
  108. // The events associated with this API.
  109. struct EventData;
  110. std::vector<std::unique_ptr<EventData>> events_;
  111. // The custom properties on the API; these are rare.
  112. struct CustomPropertyData;
  113. std::vector<std::unique_ptr<CustomPropertyData>> custom_properties_;
  114. // The pair for enum entry is <original, js-ified>. JS enum entries use
  115. // SCREAMING_STYLE (whereas our API enums are just inconsistent).
  116. using EnumEntry = std::pair<std::string, std::string>;
  117. // A map of <name, values> for the enums on this API.
  118. std::map<std::string, std::vector<EnumEntry>> enums_;
  119. // The associated properties of the API, if any.
  120. const base::DictionaryValue* property_definitions_;
  121. // The names of all the "root properties" added to the API; i.e., properties
  122. // exposed on the API object itself.
  123. base::flat_set<std::string> root_properties_;
  124. // The callback for constructing a custom type.
  125. CreateCustomType create_custom_type_;
  126. OnSilentRequest on_silent_request_;
  127. // The registered hooks for this API.
  128. std::unique_ptr<APIBindingHooks> binding_hooks_;
  129. // The reference map for all known types; required to outlive this object.
  130. APITypeReferenceMap* type_refs_;
  131. // The associated request handler, shared between this and other bindings.
  132. // Required to outlive this object.
  133. APIRequestHandler* request_handler_;
  134. // The associated event handler, shared between this and other bindings.
  135. // Required to outlive this object.
  136. APIEventHandler* event_handler_;
  137. // The associated access checker; required to outlive this object.
  138. const BindingAccessChecker* const access_checker_;
  139. // The template for this API. Note: some methods may only be available in
  140. // certain contexts, but this template contains all methods. Those that are
  141. // unavailable are removed after object instantiation.
  142. v8::Eternal<v8::ObjectTemplate> object_template_;
  143. base::WeakPtrFactory<APIBinding> weak_factory_{this};
  144. };
  145. } // namespace extensions
  146. #endif // EXTENSIONS_RENDERER_BINDINGS_API_BINDING_H_