01781a25e326e968afbc07137e3f0d43aad65664
[WebKit-https.git] / Source / Platform / chromium / public / Platform.h
1 /*
2  * Copyright (C) 2012 Google Inc. All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions are
6  * met:
7  *
8  *     * Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  *     * Redistributions in binary form must reproduce the above
11  * copyright notice, this list of conditions and the following disclaimer
12  * in the documentation and/or other materials provided with the
13  * distribution.
14  *     * Neither the name of Google Inc. nor the names of its
15  * contributors may be used to endorse or promote products derived from
16  * this software without specific prior written permission.
17  *
18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29  */
30
31 #ifndef Platform_h
32 #define Platform_h
33
34 #include "WebAudioDevice.h"
35 #include "WebCommon.h"
36 #include "WebData.h"
37 #include "WebGamepads.h"
38 #include "WebGraphicsContext3D.h"
39 #include "WebLocalizedString.h"
40 #include "WebString.h"
41 #include "WebVector.h"
42
43 namespace WebKit {
44
45 class WebAudioBus;
46 class WebBlobRegistry;
47 class WebClipboard;
48 class WebCookieJar;
49 class WebFileSystem;
50 class WebFileUtilities;
51 class WebMediaStreamCenter;
52 class WebMediaStreamCenterClient;
53 class WebMessagePortChannel;
54 class WebMimeRegistry;
55 class WebPeerConnection00Handler;
56 class WebPeerConnection00HandlerClient;
57 class WebPeerConnectionHandler;
58 class WebPeerConnectionHandlerClient;
59 class WebURL;
60 class WebURLLoader;
61 class WebSandboxSupport;
62 class WebSocketStreamHandle;
63 class WebStorageNamespace;
64 class WebThemeEngine;
65 class WebThread;
66 class WebWorkerRunLoop;
67 struct WebLocalizedString;
68
69 class Platform {
70 public:
71     // HTML5 Database ------------------------------------------------------
72
73 #ifdef WIN32
74     typedef HANDLE FileHandle;
75 #else
76     typedef int FileHandle;
77 #endif
78
79     WEBKIT_EXPORT static void initialize(Platform*);
80     WEBKIT_EXPORT static void shutdown();
81     WEBKIT_EXPORT static Platform* current();
82
83     // May return null.
84     virtual WebCookieJar* cookieJar() { return 0; }
85
86     // Must return non-null.
87     virtual WebClipboard* clipboard() { return 0; }
88
89     // Must return non-null.
90     virtual WebFileUtilities* fileUtilities() { return 0; }
91
92     // Must return non-null.
93     virtual WebMimeRegistry* mimeRegistry() { return 0; }
94
95     // May return null if sandbox support is not necessary
96     virtual WebSandboxSupport* sandboxSupport() { return 0; }
97
98     // May return null on some platforms.
99     virtual WebThemeEngine* themeEngine() { return 0; }
100
101
102     // Audio --------------------------------------------------------------
103
104     virtual double audioHardwareSampleRate() { return 0; }
105     virtual size_t audioHardwareBufferSize() { return 0; }
106     virtual WebAudioDevice* createAudioDevice(size_t bufferSize, unsigned numberOfChannels, double sampleRate, WebAudioDevice::RenderCallback*) { return 0; }
107
108
109     // Blob ----------------------------------------------------------------
110
111     // Must return non-null.
112     virtual WebBlobRegistry* blobRegistry() { return 0; }
113
114
115     // Database ------------------------------------------------------------
116
117     // Opens a database file; dirHandle should be 0 if the caller does not need
118     // a handle to the directory containing this file
119     virtual FileHandle databaseOpenFile(const WebString& vfsFileName, int desiredFlags) { return FileHandle(); }
120
121     // Deletes a database file and returns the error code
122     virtual int databaseDeleteFile(const WebString& vfsFileName, bool syncDir) { return 0; }
123
124     // Returns the attributes of the given database file
125     virtual long databaseGetFileAttributes(const WebString& vfsFileName) { return 0; }
126
127     // Returns the size of the given database file
128     virtual long long databaseGetFileSize(const WebString& vfsFileName) { return 0; }
129
130     // Returns the space available for the given origin
131     virtual long long databaseGetSpaceAvailableForOrigin(const WebKit::WebString& originIdentifier) { return 0; }
132
133
134     // DOM Storage --------------------------------------------------
135
136     // Return a LocalStorage namespace that corresponds to the following path.
137     virtual WebStorageNamespace* createLocalStorageNamespace(const WebString& path, unsigned quota) { return 0; }
138
139
140     // FileSystem ----------------------------------------------------------
141
142     // Must return non-null.
143     virtual WebFileSystem* fileSystem() { return 0; }
144
145
146     // Gamepad -------------------------------------------------------------
147
148     virtual void sampleGamepads(WebGamepads& into) { into.length = 0; }
149
150
151     // History -------------------------------------------------------------
152
153     // Returns the hash for the given canonicalized URL for use in visited
154     // link coloring.
155     virtual unsigned long long visitedLinkHash(
156         const char* canonicalURL, size_t length) { return 0; }
157
158     // Returns whether the given link hash is in the user's history. The
159     // hash must have been generated by calling VisitedLinkHash().
160     virtual bool isLinkVisited(unsigned long long linkHash) { return false; }
161
162
163     // Keygen --------------------------------------------------------------
164
165     // Handle the <keygen> tag for generating client certificates
166     // Returns a base64 encoded signed copy of a public key from a newly
167     // generated key pair and the supplied challenge string. keySizeindex
168     // specifies the strength of the key.
169     virtual WebString signedPublicKeyAndChallengeString(unsigned keySizeIndex,
170                                                         const WebString& challenge,
171                                                         const WebURL& url) { return WebString(); }
172
173
174     // Memory --------------------------------------------------------------
175
176     // Returns the current space allocated for the pagefile, in MB.
177     // That is committed size for Windows and virtual memory size for POSIX
178     virtual size_t memoryUsageMB() { return 0; }
179
180     // Same as above, but always returns actual value, without any caches.
181     virtual size_t actualMemoryUsageMB() { return 0; }
182
183     // If memory usage is below this threshold, do not bother forcing GC.
184     virtual size_t lowMemoryUsageMB() { return 256; }
185
186     // If memory usage is above this threshold, force GC more aggressively.
187     virtual size_t highMemoryUsageMB() { return 1024; }
188
189     // Delta of memory usage growth (vs. last actualMemoryUsageMB()) to force GC when memory usage is high.
190     virtual size_t highUsageDeltaMB() { return 128; }
191
192     // Returns private and shared usage, in bytes. Private bytes is the amount of
193     // memory currently allocated to this process that cannot be shared. Returns
194     // false on platform specific error conditions.
195     virtual bool processMemorySizesInBytes(size_t* privateBytes, size_t* sharedBytes) { return false; }
196
197
198     // Message Ports -------------------------------------------------------
199
200     // Creates a Message Port Channel. This can be called on any thread.
201     // The returned object should only be used on the thread it was created on.
202     virtual WebMessagePortChannel* createMessagePortChannel() { return 0; }
203
204
205     // Network -------------------------------------------------------------
206
207     // Returns a new WebURLLoader instance.
208     virtual WebURLLoader* createURLLoader() { return 0; }
209
210     // A suggestion to prefetch IP information for the given hostname.
211     virtual void prefetchHostName(const WebString&) { }
212
213     // Returns a new WebSocketStreamHandle instance.
214     virtual WebSocketStreamHandle* createSocketStreamHandle() { return 0; }
215
216     // Returns the User-Agent string that should be used for the given URL.
217     virtual WebString userAgent(const WebURL&) { return WebString(); }
218
219     // A suggestion to cache this metadata in association with this URL.
220     virtual void cacheMetadata(const WebURL&, double responseTime, const char* data, size_t dataSize) { }
221
222
223     // Resources -----------------------------------------------------------
224
225     // Returns a localized string resource (with substitution parameters).
226     virtual WebString queryLocalizedString(WebLocalizedString::Name) { return WebString(); }
227     virtual WebString queryLocalizedString(WebLocalizedString::Name, const WebString& parameter) { return WebString(); }
228     virtual WebString queryLocalizedString(WebLocalizedString::Name, const WebString& parameter1, const WebString& parameter2) { return WebString(); }
229
230
231     // Threads -------------------------------------------------------
232
233     // Creates an embedder-defined thread.
234     virtual WebThread* createThread(const char* name) { return 0; }
235
236     // Returns an interface to the current thread. This is owned by the
237     // embedder.
238     virtual WebThread* currentThread() { return 0; }
239
240
241     // Profiling -----------------------------------------------------------
242
243     virtual void decrementStatsCounter(const char* name) { }
244     virtual void incrementStatsCounter(const char* name) { }
245
246
247     // Resources -----------------------------------------------------------
248
249     // Returns a blob of data corresponding to the named resource.
250     virtual WebData loadResource(const char* name) { return WebData(); }
251
252     // Decodes the in-memory audio file data and returns the linear PCM audio data in the destinationBus.
253     // A sample-rate conversion to sampleRate will occur if the file data is at a different sample-rate.
254     // Returns true on success.
255     virtual bool loadAudioResource(WebAudioBus* destinationBus, const char* audioFileData, size_t dataSize, double sampleRate) { return false; }
256
257
258     // Sandbox ------------------------------------------------------------
259
260     // In some browsers, a "sandbox" restricts what operations a program
261     // is allowed to preform. Such operations are typically abstracted out
262     // via this API, but sometimes (like in HTML 5 database opening) WebKit
263     // needs to behave differently based on whether it's restricted or not.
264     // In these cases (and these cases only) you can call this function.
265     // It's OK for this value to be conservitive (i.e. true even if the
266     // sandbox isn't active).
267     virtual bool sandboxEnabled() { return false; }
268
269
270     // Screen -------------------------------------------------------------
271
272     // Supplies the system monitor color profile.
273     virtual void screenColorProfile(WebVector<char>* profile) { }
274
275
276     // Sudden Termination --------------------------------------------------
277
278     // Disable/Enable sudden termination.
279     virtual void suddenTerminationChanged(bool enabled) { }
280
281
282     // System --------------------------------------------------------------
283
284     // Returns a value such as "en-US".
285     virtual WebString defaultLocale() { return WebString(); }
286
287     // Wall clock time in seconds since the epoch.
288     virtual double currentTime() { return 0; }
289
290     // Monotonically increasing time in seconds from an arbitrary fixed point in the past.
291     // This function is expected to return at least millisecond-precision values. For this reason,
292     // it is recommended that the fixed point be no further in the past than the epoch.
293     virtual double monotonicallyIncreasingTime() { return 0; }
294
295     // WebKit clients must implement this funcion if they use cryptographic randomness.
296     virtual void cryptographicallyRandomValues(unsigned char* buffer, size_t length) = 0;
297
298     // Delayed work is driven by a shared timer.
299     typedef void (*SharedTimerFunction)();
300     virtual void setSharedTimerFiredFunction(SharedTimerFunction timerFunction) { }
301     virtual void setSharedTimerFireInterval(double) { }
302     virtual void stopSharedTimer() { }
303
304     // Callable from a background WebKit thread.
305     virtual void callOnMainThread(void (*func)(void*), void* context) { }
306
307
308     // Tracing -------------------------------------------------------------
309
310     // Get a pointer to the enabled state of the given trace category. The
311     // embedder can dynamically change the enabled state as trace event
312     // recording is started and stopped by the application. Only long-lived
313     // literal strings should be given as the category name. The implementation
314     // expects the returned pointer to be held permanently in a local static. If
315     // the unsigned char is non-zero, tracing is enabled. If tracing is enabled,
316     // addTraceEvent is expected to be called by the trace event macros.
317     virtual const unsigned char* getTraceCategoryEnabledFlag(const char* categoryName) { return 0; }
318
319     // Add a trace event to the platform tracing system. Depending on the actual
320     // enabled state, this event may be recorded or dropped. Returns
321     // thresholdBeginId for use in a corresponding end addTraceEvent call.
322     // - phase specifies the type of event:
323     //   - BEGIN ('B'): Marks the beginning of a scoped event.
324     //   - END ('E'): Marks the end of a scoped event.
325     //   - INSTANT ('I'): Standalone, instantaneous event.
326     //   - START ('S'): Marks the beginning of an asynchronous event (the end
327     //     event can occur in a different scope or thread). The id parameter is
328     //     used to match START/FINISH pairs.
329     //   - FINISH ('F'): Marks the end of an asynchronous event.
330     //   - COUNTER ('C'): Used to trace integer quantities that change over
331     //     time. The argument values are expected to be of type int.
332     //   - METADATA ('M'): Reserved for internal use.
333     // - categoryEnabled is the pointer returned by getTraceCategoryEnabledFlag.
334     // - name is the name of the event. Also used to match BEGIN/END and
335     //   START/FINISH pairs.
336     // - id optionally allows events of the same name to be distinguished from
337     //   each other. For example, to trace the consutruction and destruction of
338     //   objects, specify the pointer as the id parameter.
339     // - numArgs specifies the number of elements in argNames, argTypes, and
340     //   argValues.
341     // - argNames is the array of argument names. Use long-lived literal strings
342     //   or specify the COPY flag.
343     // - argTypes is the array of argument types:
344     //   - BOOL (1): bool
345     //   - UINT (2): unsigned long long
346     //   - INT (3): long long
347     //   - DOUBLE (4): double
348     //   - POINTER (5): void*
349     //   - STRING (6): char* (long-lived null-terminated char* string)
350     //   - COPY_STRING (7): char* (temporary null-terminated char* string)
351     // - argValues is the array of argument values. Each value is the unsigned
352     //   long long member of a union of all supported types.
353     // - thresholdBeginId optionally specifies the value returned by a previous
354     //   call to addTraceEvent with a BEGIN phase.
355     // - threshold is used on an END phase event in conjunction with the
356     //   thresholdBeginId of a prior BEGIN event. The threshold is the minimum
357     //   number of microseconds that must have passed since the BEGIN event. If
358     //   less than threshold microseconds has passed, the BEGIN/END pair is
359     //   dropped.
360     // - flags can be 0 or one or more of the following, ORed together:
361     //   - COPY (0x1): treat all strings (name, argNames and argValues of type
362     //     string) as temporary so that they will be copied by addTraceEvent.
363     //   - HAS_ID (0x2): use the id argument to uniquely identify the event for
364     //     matching with other events of the same name.
365     //   - MANGLE_ID (0x4): specify this flag if the id parameter is the value
366     //     of a pointer.
367     virtual int addTraceEvent(
368         char phase,
369         const unsigned char* categoryEnabledFlag,
370         const char* name,
371         unsigned long long id,
372         int numArgs,
373         const char** argNames,
374         const unsigned char* argTypes,
375         const unsigned long long* argValues,
376         int thresholdBeginId,
377         long long threshold,
378         unsigned char flags) { return -1; }
379
380     // Callbacks for reporting histogram data.
381     // CustomCounts histogram has exponential bucket sizes, so that min=1, max=1000000, bucketCount=50 would do.
382     virtual void histogramCustomCounts(const char* name, int sample, int min, int max, int bucketCount) { }
383     // Enumeration histogram buckets are linear, boundaryValue should be larger than any possible sample value.
384     virtual void histogramEnumeration(const char* name, int sample, int boundaryValue) { }
385
386
387     // GPU ----------------------------------------------------------------
388     //
389     // May return null if GPU is not supported.
390     // Returns newly allocated and initialized offscreen WebGraphicsContext3D instance.
391     virtual WebGraphicsContext3D* createOffscreenGraphicsContext3D(const WebGraphicsContext3D::Attributes&) { return 0; }
392
393     // Returns true if the platform is capable of producing an offscreen context suitable for accelerating 2d canvas.
394     // This will return false if the platform cannot promise that contexts will be preserved across operations like
395     // locking the screen or if the platform cannot provide a context with suitable performance characteristics.
396     //
397     // This value must be checked again after a context loss event as the platform's capabilities may have changed.
398     virtual bool canAccelerate2dCanvas() { return false; }
399
400
401     // WebRTC ----------------------------------------------------------
402
403     // DEPRECATED
404     // Creates an WebPeerConnectionHandler for DeprecatedPeerConnection.
405     // May return null if WebRTC functionality is not avaliable or out of resources.
406     virtual WebPeerConnectionHandler* createPeerConnectionHandler(WebPeerConnectionHandlerClient*) { return 0; }
407
408     // Creates an WebPeerConnection00Handler for PeerConnection00.
409     // This is an highly experimental feature not yet in the WebRTC standard.
410     // May return null if WebRTC functionality is not avaliable or out of resources.
411     virtual WebPeerConnection00Handler* createPeerConnection00Handler(WebPeerConnection00HandlerClient*) { return 0; }
412
413     // May return null if WebRTC functionality is not avaliable or out of resources.
414     virtual WebMediaStreamCenter* createMediaStreamCenter(WebMediaStreamCenterClient*) { return 0; }
415
416
417     // WebWorker ----------------------------------------------------------
418
419     virtual void didStartWorkerRunLoop(const WebWorkerRunLoop&) { }
420     virtual void didStopWorkerRunLoop(const WebWorkerRunLoop&) { }
421
422 protected:
423     ~Platform() { }
424 };
425
426 } // namespace WebKit
427
428 #endif