Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code

Side by Side Diff: include/AdblockPlus/JsEngine.h

Issue 5728380594946048: Issue 116 - Document the libadblockplus API (Closed)
Patch Set: Addressed remaining comments Created Sept. 2, 2014, 5:21 a.m.
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments.
Jump to:
View unified diff | Download patch
« no previous file with comments | « include/AdblockPlus/FilterEngine.h ('k') | include/AdblockPlus/JsValue.h » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 /* 1 /*
2 * This file is part of Adblock Plus <http://adblockplus.org/>, 2 * This file is part of Adblock Plus <http://adblockplus.org/>,
3 * Copyright (C) 2006-2014 Eyeo GmbH 3 * Copyright (C) 2006-2014 Eyeo GmbH
4 * 4 *
5 * Adblock Plus is free software: you can redistribute it and/or modify 5 * Adblock Plus is free software: you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License version 3 as 6 * it under the terms of the GNU General Public License version 3 as
7 * published by the Free Software Foundation. 7 * published by the Free Software Foundation.
8 * 8 *
9 * Adblock Plus is distributed in the hope that it will be useful, 9 * Adblock Plus is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
(...skipping 27 matching lines...) Expand all
38 class Isolate; 38 class Isolate;
39 class Value; 39 class Value;
40 class Context; 40 class Context;
41 template<class T> class Handle; 41 template<class T> class Handle;
42 typedef Handle<Value>(*InvocationCallback)(const Arguments &args); 42 typedef Handle<Value>(*InvocationCallback)(const Arguments &args);
43 } 43 }
44 44
45 namespace AdblockPlus 45 namespace AdblockPlus
46 { 46 {
47 class JsEngine; 47 class JsEngine;
48
49 /**
50 * Shared smart pointer to a `JsEngine` instance.
51 */
48 typedef std::tr1::shared_ptr<JsEngine> JsEnginePtr; 52 typedef std::tr1::shared_ptr<JsEngine> JsEnginePtr;
49 53
54 /**
55 * JavaScript engine used by `FilterEngine`, wraps v8.
56 */
50 class JsEngine : public std::tr1::enable_shared_from_this<JsEngine> 57 class JsEngine : public std::tr1::enable_shared_from_this<JsEngine>
51 { 58 {
52 friend class JsValue; 59 friend class JsValue;
53 friend class JsContext; 60 friend class JsContext;
54 61
55 public: 62 public:
63 /**
64 * Event callback function.
65 */
56 typedef std::tr1::function<void(JsValueList& params)> EventCallback; 66 typedef std::tr1::function<void(JsValueList& params)> EventCallback;
67
68 /**
69 * Maps events to callback functions.
70 */
57 typedef std::map<std::string, EventCallback> EventMap; 71 typedef std::map<std::string, EventCallback> EventMap;
58 72
73 /**
74 * Creates a new JavaScript engine instance.
75 * @param appInfo Information about the app, used for update checks.
76 * @return New `JsEngine` instance.
77 */
59 static JsEnginePtr New(const AppInfo& appInfo = AppInfo()); 78 static JsEnginePtr New(const AppInfo& appInfo = AppInfo());
79
80 /**
81 * Registers the callback function for an event.
82 * @param eventName Event name. Note that this can be any string - it's a
83 * general purpose event handling mechanism.
84 * @param callback Event callback function.
85 */
60 void SetEventCallback(const std::string& eventName, EventCallback callback); 86 void SetEventCallback(const std::string& eventName, EventCallback callback);
87
88 /**
89 * Removes the callback function for an event.
90 * @param eventName Event name.
91 */
61 void RemoveEventCallback(const std::string& eventName); 92 void RemoveEventCallback(const std::string& eventName);
93
94 /**
95 * Triggers an event.
96 * @param eventName Event name.
97 * @param params Event parameters.
98 */
62 void TriggerEvent(const std::string& eventName, JsValueList& params); 99 void TriggerEvent(const std::string& eventName, JsValueList& params);
100
101 /**
102 * Evaluates a JavaScript expression.
103 * @param source JavaScript expression to evaluate.
104 * @param filename Optional file name for the expression, used in error
105 * messages.
106 * @return Result of the evaluated expression.
107 */
63 JsValuePtr Evaluate(const std::string& source, 108 JsValuePtr Evaluate(const std::string& source,
64 const std::string& filename = ""); 109 const std::string& filename = "");
110
111 /**
112 * Initiates a garbage collection.
113 */
65 void Gc(); 114 void Gc();
115
116 //@{
117 /**
118 * Creates a new JavaScript value.
119 * @param val Value to convert.
120 * @return New `JsValue` instance.
121 */
66 JsValuePtr NewValue(const std::string& val); 122 JsValuePtr NewValue(const std::string& val);
67 JsValuePtr NewValue(int64_t val); 123 JsValuePtr NewValue(int64_t val);
68 JsValuePtr NewValue(bool val); 124 JsValuePtr NewValue(bool val);
69 inline JsValuePtr NewValue(const char* val) 125 inline JsValuePtr NewValue(const char* val)
70 { 126 {
71 return NewValue(std::string(val)); 127 return NewValue(std::string(val));
72 } 128 }
73 inline JsValuePtr NewValue(int val) 129 inline JsValuePtr NewValue(int val)
74 { 130 {
75 return NewValue(static_cast<int64_t>(val)); 131 return NewValue(static_cast<int64_t>(val));
76 } 132 }
77 #ifdef __APPLE__ 133 #ifdef __APPLE__
78 inline JsValuePtr NewValue(long val) 134 inline JsValuePtr NewValue(long val)
79 { 135 {
80 return NewValue(static_cast<int64_t>(val)); 136 return NewValue(static_cast<int64_t>(val));
81 } 137 }
82 #endif 138 #endif
139 //@}
140
141 /**
142 * Creates a new JavaScript object.
143 * @return New `JsValue` instance.
144 */
83 JsValuePtr NewObject(); 145 JsValuePtr NewObject();
146
147 /**
148 * Creates a JavaScript function that invokes a C++ callback.
149 * @param callback C++ callback to invoke. The callback receives a
150 * `v8::Arguments` object and can use `FromArguments()` to retrieve
151 * the current `JsEngine`.
152 * @return New `JsValue` instance.
153 */
84 JsValuePtr NewCallback(v8::InvocationCallback callback); 154 JsValuePtr NewCallback(v8::InvocationCallback callback);
155
156 /**
157 * Returns a `JsEngine` instance contained in a `v8::Arguments` object.
158 * Use this in callbacks created via `NewCallback()` to retrieve the current
159 * `JsEngine`.
160 * @param arguments `v8::Arguments` object containing the `JsEngine`
161 * instance.
162 * @return `JsEngine` instance from `v8::Arguments`.
163 */
85 static JsEnginePtr FromArguments(const v8::Arguments& arguments); 164 static JsEnginePtr FromArguments(const v8::Arguments& arguments);
165
166 /**
167 * Converts v8 arguments to `JsValue` objects.
168 * @param arguments `v8::Arguments` object containing the arguments to
169 * convert.
170 * @return List of arguments converted to `JsValue` objects.
171 */
86 JsValueList ConvertArguments(const v8::Arguments& arguments); 172 JsValueList ConvertArguments(const v8::Arguments& arguments);
87 173
174 /**
175 * @see `SetFileSystem()`.
176 */
88 FileSystemPtr GetFileSystem(); 177 FileSystemPtr GetFileSystem();
178
179 /**
180 * Sets the `FileSystem` implementation used for all file I/O.
181 * Setting this is optional, the engine will use a `DefaultFileSystem`
182 * instance by default, which might be sufficient.
183 * @param The `FileSystem` instance to use.
184 */
89 void SetFileSystem(FileSystemPtr val); 185 void SetFileSystem(FileSystemPtr val);
186
187 /**
188 * @see `SetWebRequest()`.
189 */
90 WebRequestPtr GetWebRequest(); 190 WebRequestPtr GetWebRequest();
191
192 /**
193 * Sets the `WebRequest` implementation used for XMLHttpRequests.
194 * Setting this is optional, the engine will use a `DefaultWebRequest`
195 * instance by default, which might be sufficient.
196 * @param The `WebRequest` instance to use.
197 */
91 void SetWebRequest(WebRequestPtr val); 198 void SetWebRequest(WebRequestPtr val);
199
200 /**
201 * @see `SetLogSystem()`.
202 */
92 LogSystemPtr GetLogSystem(); 203 LogSystemPtr GetLogSystem();
204
205 /**
206 * Sets the `LogSystem` implementation used for logging (e.g. to handle
207 * `console.log()` calls from JavaScript).
208 * Setting this is optional, the engine will use a `DefaultLogSystem`
209 * instance by default, which might be sufficient.
210 * @param The `LogSystem` instance to use.
211 */
93 void SetLogSystem(LogSystemPtr val); 212 void SetLogSystem(LogSystemPtr val);
94 213
95 private: 214 private:
96 JsEngine(); 215 JsEngine();
97 216
98 FileSystemPtr fileSystem; 217 FileSystemPtr fileSystem;
99 WebRequestPtr webRequest; 218 WebRequestPtr webRequest;
100 LogSystemPtr logSystem; 219 LogSystemPtr logSystem;
101 v8::Isolate* isolate; 220 v8::Isolate* isolate;
102 V8ValueHolder<v8::Context> context; 221 V8ValueHolder<v8::Context> context;
103 EventMap eventCallbacks; 222 EventMap eventCallbacks;
104 }; 223 };
105 } 224 }
106 225
107 #endif 226 #endif
OLDNEW
« no previous file with comments | « include/AdblockPlus/FilterEngine.h ('k') | include/AdblockPlus/JsValue.h » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld