v8_value_converter.h revision c2db58bd994c04d98e4ee2cd7565b71548655fe3 
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
11namespace base {
12class Value;
13}
14
15namespace 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.).
25class 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_
97