v8_value_converter.h revision cedac228d2dd51db4b79ea1e72c7f249408ee061 
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 "base/callback.h"
9#include "content/common/content_export.h"
10#include "v8/include/v8.h"
11
12namespace base {
13class Value;
14}
15
16namespace 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.).
26class 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::Handle<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::Handle<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::Handle<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::Handle<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::Handle<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::Handle<v8::Value> ToV8Value(
109      const base::Value* value,
110      v8::Handle<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::Handle<v8::Value> value,
122                                   v8::Handle<v8::Context> context) const = 0;
123};
124
125}  // namespace content
126
127#endif  // CONTENT_PUBLIC_RENDERER_V8_VALUE_CONVERTER_H_
128