content/public/child/v8_value_converter.h

   1 // Copyright (c) 2012 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 CONTENT_PUBLIC_CHILD_V8_VALUE_CONVERTER_H_
   6 #define CONTENT_PUBLIC_CHILD_V8_VALUE_CONVERTER_H_
   7
   8 #include "base/callback.h"
   9 #include "content/common/content_export.h"
  10 #include "v8/include/v8.h"
  11
  12 namespace base {
  13 class Value;
  14 }
  15
  16 namespace content {
  17
  18 // Converts between v8::Value (JavaScript values in the v8 heap) and Chrome's
  19 // values (from base/values.h). Lists and dictionaries are converted
  20 // recursively.
  21 //
  22 // The JSON types (null, boolean, string, number, array, and object) as well as
  23 // binary values are supported. For binary values, we convert to WebKit
  24 // ArrayBuffers, and support converting from an ArrayBuffer or any of the
  25 // ArrayBufferView subclasses (Uint8Array, etc.).
  26 class CONTENT_EXPORT V8ValueConverter {
  27  public:
  28   // Extends the default behaviour of V8ValueConverter.
  29   class CONTENT_EXPORT Strategy {
  30    public:
  31     typedef base::Callback<base::Value*(
  32         v8::Local<v8::Value>, v8::Isolate* isolate)> FromV8ValueCallback;
  33
  34     virtual ~Strategy() {}
  35
  36     // If false is returned, V8ValueConverter proceeds with the default
  37     // behavior.
  38     // Use |callback| to convert any child values, as this will retain
  39     // the ValueConverter's internal checks for depth and cycles.
  40     virtual bool FromV8Object(v8::Local<v8::Object> value,
  41                               base::Value** out,
  42                               v8::Isolate* isolate,
  43                               const FromV8ValueCallback& callback) const;
  44
  45     // If false is returned, V8ValueConverter proceeds with the default
  46     // behavior.
  47     // Use |callback| to convert any child values, as this will retain
  48     // the ValueConverter's internal checks for depth and cycles.
  49     virtual bool FromV8Array(v8::Local<v8::Array> value,
  50                              base::Value** out,
  51                              v8::Isolate* isolate,
  52                              const FromV8ValueCallback& callback) const;
  53
  54     // If false is returned, V8ValueConverter proceeds with the default
  55     // behavior. v8::Object is passed as ArrayBuffer and ArrayBufferView
  56     // classes are siblings.
  57     virtual bool FromV8ArrayBuffer(v8::Local<v8::Object> value,
  58                                    base::Value** out,
  59                                    v8::Isolate* isolate) const;
  60
  61     // If false is returned, V8ValueConverter proceeds with the default
  62     // behavior. This allows to intercept "non-finite" values and do something
  63     // with them.
  64     virtual bool FromV8Number(v8::Local<v8::Number> value,
  65                               base::Value** out) const;
  66
  67     // If false is returned, V8ValueConverter proceeds with the default
  68     // behavior.
  69     virtual bool FromV8Undefined(base::Value** out) const;
  70   };
  71
  72   static V8ValueConverter* create();
  73
  74   virtual ~V8ValueConverter() {}
  75
  76   // If true, Date objects are converted into DoubleValues with the number of
  77   // seconds since Unix epoch.
  78   //
  79   // Otherwise they are converted into DictionaryValues with whatever additional
  80   // properties has been set on them.
  81   virtual void SetDateAllowed(bool val) = 0;
  82
  83   // If true, RegExp objects are converted into StringValues with the regular
  84   // expression between / and /, for example "/ab?c/".
  85   //
  86   // Otherwise they are converted into DictionaryValues with whatever additional
  87   // properties has been set on them.
  88   virtual void SetRegExpAllowed(bool val) = 0;
  89
  90   // If true, Function objects are converted into DictionaryValues with whatever
  91   // additional properties has been set on them.
  92   //
  93   // Otherwise they are treated as unsupported, see FromV8Value.
  94   virtual void SetFunctionAllowed(bool val) = 0;
  95
  96   // If true, null values are stripped from objects. This is often useful when
  97   // converting arguments to extension APIs.
  98   virtual void SetStripNullFromObjects(bool val) = 0;
  99
 100   // Extend default behavior of V8ValueConverter.
 101   virtual void SetStrategy(Strategy* strategy) = 0;
 102
 103   // Converts a base::Value to a v8::Value.
 104   //
 105   // Unsupported types are replaced with null.  If an array or object throws
 106   // while setting a value, that property or item is skipped, leaving a hole in
 107   // the case of arrays.
 108   virtual v8::Local<v8::Value> ToV8Value(
 109       const base::Value* value,
 110       v8::Local<v8::Context> context) const = 0;
 111
 112   // Converts a v8::Value to base::Value.
 113   //
 114   // Unsupported types (unless explicitly configured) are not converted, so
 115   // this method may return NULL -- the exception is when converting arrays,
 116   // where unsupported types are converted to Value(TYPE_NULL).
 117   //
 118   // Likewise, if an object throws while converting a property it will not be
 119   // converted, whereas if an array throws while converting an item it will be
 120   // converted to Value(TYPE_NULL).
 121   virtual base::Value* FromV8Value(v8::Local<v8::Value> value,
 122                                    v8::Local<v8::Context> context) const = 0;
 123 };
 124
 125 }  // namespace content
 126
 127 #endif  // CONTENT_PUBLIC_CHILD_V8_VALUE_CONVERTER_H_