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