1/*
2 * Copyright (C) 2012 Google Inc. All rights reserved.
3 * Copyright (C) 2013 Apple Inc. All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * 1.  Redistributions of source code must retain the above copyright
10 *     notice, this list of conditions and the following disclaimer.
11 * 2.  Redistributions in binary form must reproduce the above copyright
12 *     notice, this list of conditions and the following disclaimer in the
13 *     documentation and/or other materials provided with the distribution.
14 *
15 * THIS SOFTWARE IS PROVIDED BY APPLE AND ITS CONTRIBUTORS "AS IS" AND ANY
16 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
17 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
18 * DISCLAIMED. IN NO EVENT SHALL APPLE OR ITS CONTRIBUTORS BE LIABLE FOR ANY
19 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
20 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
21 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
22 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
24 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25 */
26
27[
28    DoNotCheckConstants
29] interface Internals {
30    GCObservation observeGC(any observed);
31
32    [RaisesException] DOMString elementLayoutTreeAsText(Element element);
33    boolean isPreloaded(DOMString url);
34    boolean isPreloadedBy(DOMString url, Document document);
35    boolean isLoading(DOMString url);
36    boolean isLoadingFromMemoryCache(DOMString url);
37
38    // Call this function with the URL of a resource that has not yet been
39    // fetched. It returns a promise that resolves with the priority of the
40    // request, once it has been made.
41    [CallWith=ScriptState] Promise<unsigned long> getResourcePriority(DOMString url, Document document);
42
43    DOMString getResourceHeader(DOMString url, DOMString header, Document document);
44
45    boolean doesWindowHaveUrlFragment(Window window);
46
47    CSSStyleDeclaration computedStyleIncludingVisitedInfo(Node node);
48
49    ShadowRoot createUserAgentShadowRoot(Element host);
50
51    ShadowRoot shadowRoot(Element host);
52
53    void setBrowserControlsState(float top_height, float bottom_height, boolean shrinksLayout);
54    void setBrowserControlsShownRatio(float top_ratio, float bottom_ratio);
55
56    Node effectiveRootScroller(Document document);
57
58    [RaisesException] DOMString shadowRootType(Node root);
59    [RaisesException] boolean hasShadowInsertionPoint(Node root);
60    [RaisesException] boolean hasContentElement(Node root);
61    [RaisesException] unsigned long countElementShadow(Node Root);
62    DOMString shadowPseudoId(Element element);
63    [RaisesException] boolean isValidContentSelect(Element contentElement);
64    Node treeScopeRootNode(Node node);
65    Node parentTreeScope(Node node);
66    [RaisesException] unsigned short compareTreeScopePosition(Node treeScope1, Node treeScope2);
67    [RaisesException] unsigned long updateStyleAndReturnAffectedElementCount();
68    [RaisesException] unsigned long needsLayoutCount();
69    [RaisesException] unsigned long hitTestCount(Document document);
70    [RaisesException] unsigned long hitTestCacheHits(Document document);
71    [RaisesException] Element? elementFromPoint(Document document, double x, double y, boolean ignoreClipping, boolean allowChildFrameContent);
72    [RaisesException] void clearHitTestCache(Document document);
73
74    // Allows inspection of the inner editor node.
75    [RaisesException] Element? innerEditorElement(Element container);
76
77    // Animation testing.
78    [RaisesException] void pauseAnimations(double pauseTime);
79    boolean isCompositedAnimation(Animation animation);
80    void disableCompositedAnimation(Animation animation);
81
82    // Advances an animated image. For BitmapImage (e.g., animated gifs) this
83    // will advance to the next frame. For SVGImage, this will trigger an
84    // animation update for CSS and advance the SMIL timeline by one frame.
85    [RaisesException] void advanceImageAnimation(Element image);
86
87    [RaisesException] Node nextSiblingInFlatTree(Node node);
88    [RaisesException] Node firstChildInFlatTree(Node node);
89    [RaisesException] Node lastChildInFlatTree(Node node);
90    [RaisesException] Node nextInFlatTree(Node node);
91    [RaisesException] Node previousInFlatTree(Node node);
92
93    DOMString visiblePlaceholder(Element element);
94    boolean isValidationMessageVisible(Element element);
95    void selectColorInColorChooser(Element element, DOMString colorValue);
96    void endColorChooser(Element element);
97
98    // If the argument is omitted, the top-level document is used.
99    boolean hasAutofocusRequest(optional Document document);
100    [RaisesException] sequence<DOMString> formControlStateOfHistoryItem();
101    [RaisesException] void setFormControlStateOfHistoryItem(sequence<DOMString> values);
102    readonly attribute Window pagePopupWindow;
103
104    [RaisesException] DOMRectReadOnly absoluteCaretBounds();
105
106    DOMRectReadOnly boundingBox(Element element);
107
108    [RaisesException] void setMarker(Document document, Range range, DOMString markerType);
109    [RaisesException] unsigned long markerCountForNode(Node node, DOMString markerType);
110    unsigned long activeMarkerCountForNode(Node node);
111    [RaisesException] Range markerRangeForNode(Node node, DOMString markerType, unsigned long index);
112    [RaisesException] DOMString markerDescriptionForNode(Node node, DOMString markerType, unsigned long index);
113    [RaisesException] unsigned long markerBackgroundColorForNode(Node node, DOMString markerType, unsigned long index);
114    [RaisesException] unsigned long markerUnderlineColorForNode(Node node, DOMString markerType, unsigned long index);
115    [RaisesException] void addTextMatchMarker(Range range, DOMString matchStatus);
116    [RaisesException] void addCompositionMarker(Range range, DOMString underlineColorValue, DOMString thicknessValue, DOMString underlineStyleValue, DOMString textColorValue, DOMString backgroundColorValue);
117    [RaisesException] void addActiveSuggestionMarker(Range range, DOMString underlineColorValue, DOMString thicknessValue, DOMString backgroundColorValue);
118    [RaisesException] void addSuggestionMarker(Range range, sequence<DOMString> suggestions, DOMString suggestionHighlightColorValue, DOMString underlineColorValue, DOMString thicknessValue, DOMString backgroundColorValue);
119    void setTextMatchMarkersActive(Node node, unsigned long startOffset, unsigned long endOffset, boolean active);
120    void setMarkedTextMatchesAreHighlighted(Document document, boolean highlight);
121
122    [RaisesException] DOMString viewportAsText(Document document,
123                                               float devicePixelRatio,
124                                               long availableWidth,
125                                               long availableHeight);
126
127    [RaisesException] boolean elementShouldAutoComplete(Element inputElement);
128    [RaisesException] DOMString suggestedValue(Element inputElement);
129    [RaisesException] void setSuggestedValue(Element inputElement, DOMString value);
130    [RaisesException] void setAutofilledValue(Element inputElement, DOMString value);
131    [RaisesException] void setEditingValue(Element inputElement, DOMString value);
132    [RaisesException] void setAutofilled(Element inputElement, boolean enabled);
133
134    Range rangeFromLocationAndLength(Element scope, long rangeLocation, long rangeLength);
135    unsigned long locationFromRange(Element scope, Range range);
136    unsigned long lengthFromRange(Element scope, Range range);
137    DOMString rangeAsText(Range range);
138
139    [RaisesException] DOMPoint touchPositionAdjustedToBestClickableNode(long x, long y, long width, long height, Document document);
140    [RaisesException] Node touchNodeAdjustedToBestClickableNode(long x, long y, long width, long height, Document document);
141    [RaisesException] DOMPoint touchPositionAdjustedToBestContextMenuNode(long x, long y, long width, long height, Document document);
142    [RaisesException] Node touchNodeAdjustedToBestContextMenuNode(long x, long y, long width, long height, Document document);
143
144    [RaisesException] long lastSpellCheckRequestSequence(Document document);
145    [RaisesException] long lastSpellCheckProcessedSequence(Document document);
146    [RaisesException] void cancelCurrentSpellCheckRequest(Document document);
147    [RaisesException] DOMString idleTimeSpellCheckerState(Document document);
148    [RaisesException] void runIdleTimeSpellChecker(Document document);
149
150    sequence<DOMString> userPreferredLanguages();
151    void setUserPreferredLanguages(sequence<DOMString> languages);
152    void setSystemTimeZone(DOMString timezone);
153
154    unsigned long mediaKeysCount();
155    unsigned long mediaKeySessionCount();
156    unsigned long wheelEventHandlerCount(Document document);
157    unsigned long scrollEventHandlerCount(Document document);
158    unsigned long touchStartOrMoveEventHandlerCount(Document document);
159    unsigned long touchEndOrCancelEventHandlerCount(Document document);
160    unsigned long pointerEventHandlerCount(Document document);
161    [RaisesException] HitTestLayerRectList touchEventTargetLayerRects(Document document);
162
163    [RaisesException] boolean executeCommand(Document document, DOMString name, DOMString value);
164
165    void triggerTestInspectorIssue(Document document);
166
167    DOMString htmlNamespace();
168    sequence<DOMString> htmlTags();
169    DOMString svgNamespace();
170    sequence<DOMString> svgTags();
171
172    [RaisesException] NodeList nodesFromRect(Document document, long x, long y,
173        unsigned long width, unsigned long height, boolean ignoreClipping,
174        boolean allowChildFrameContent);
175
176    [RaisesException] boolean hasSpellingMarker(Document document, long from, long length);
177    [RaisesException] boolean hasGrammarMarker(Document document, long from, long length);
178    [RaisesException] void replaceMisspelled(Document document, DOMString replacement);
179
180    boolean canHyphenate(DOMString locale);
181    void setMockHyphenation(DOMString locale);
182
183    boolean isOverwriteModeEnabled(Document document);
184    void toggleOverwriteModeEnabled(Document document);
185
186    unsigned long numberOfScrollableAreas(Document document);
187
188    boolean isPageBoxVisible(Document document, long pageNumber);
189
190    readonly attribute InternalSettings settings;
191    readonly attribute InternalRuntimeFlags runtimeFlags;
192    readonly attribute unsigned long workerThreadCount;
193    readonly attribute boolean isFormControlsRefreshEnabled;
194
195    // Flag for layerTreeAsText. The value must be kept in sync with the value
196    // of LayerTreeFlags in layers_as_json.h.
197    // Other flags in LayerTreeFlags are not supported in internals API.
198    const unsigned short LAYER_TREE_INCLUDES_INVALIDATIONS = 2;
199    const unsigned short LAYER_TREE_INCLUDES_DETAILED_INVALIDATIONS = 4;
200
201    [RaisesException] DOMString layerTreeAsText(Document document, optional unsigned short flags);
202
203    [RaisesException] boolean scrollsWithRespectTo(Element element1, Element element2);
204
205    DOMString scrollingStateTreeAsText(Document document);
206    [RaisesException] DOMString mainThreadScrollingReasons(Document document);
207    [RaisesException] DOMRectList nonFastScrollableRects(Document document);
208    [RaisesException] void markGestureScrollRegionDirty(Document document);
209
210    void evictAllResources();
211
212    unsigned long numberOfLiveNodes();
213    unsigned long numberOfLiveDocuments();
214
215    DOMString counterValue(Element element);
216    [RaisesException] long pageNumber(Element element, optional float pageWidth = 800, optional float pageHeight = 600);
217    sequence<DOMString> shortcutIconURLs(Document document);
218    sequence<DOMString> allIconURLs(Document document);
219    [RaisesException] long numberOfPages(optional double pageWidthInPixels = 800, optional double pageHeightInPixels = 600);
220    [RaisesException] DOMString pageProperty(DOMString propertyName, long pageNumber);
221    [RaisesException] DOMString pageSizeAndMarginsInPixels(long pageIndex, long width, long height, long marginTop, long marginRight, long marginBottom, long marginLeft);
222
223    [RaisesException] float pageScaleFactor();
224    [RaisesException] void setPageScaleFactor(float scaleFactor);
225    [RaisesException] void setPageScaleFactorLimits(float minScaleFactor, float maxScaleFactor);
226
227    [RaisesException] void setIsCursorVisible(Document document, boolean isVisible);
228
229    // HTMLMediaElement, HTMLAudioElement and HTMLVideoElement.
230    DOMString effectivePreload(HTMLMediaElement mediaElement);
231    void mediaPlayerRemoteRouteAvailabilityChanged(HTMLMediaElement mediaElement, boolean available);
232    void mediaPlayerPlayingRemotelyChanged(HTMLMediaElement mediaElement, boolean remote);
233    void setPersistent(HTMLVideoElement video, boolean persistent);
234    void forceStaleStateForMediaElement(HTMLMediaElement mediaElement, long state);
235    boolean isMediaElementSuspended(HTMLMediaElement mediaElement);
236    void setMediaControlsTestMode(HTMLMediaElement mediaElement, boolean enable);
237
238    void registerURLSchemeAsBypassingContentSecurityPolicy(DOMString scheme);
239    void registerURLSchemeAsBypassingContentSecurityPolicy(DOMString scheme, sequence<DOMString> policyAreas);
240    void removeURLSchemeRegisteredAsBypassingContentSecurityPolicy(DOMString scheme);
241
242    TypeConversions typeConversions();
243
244    sequence<DOMString> getReferencedFilePaths();
245
246    // These functions both reset the tracked repaint rects. They are intended to be used in the following order:
247    //  startTrackingRepaints(), repaintRectsAsText(), stopTrackingRepaints().
248    [RaisesException] void startTrackingRepaints(Document document);
249    [RaisesException] void stopTrackingRepaints(Document document);
250
251    // |node| should be Document, HTMLIFrameElement, or unspecified.
252    // If |node| is an HTMLIFrameElement, it assumes node.contentDocument is
253    // specified without security checks. Unspecified means this document.
254    [RaisesException] void updateLayoutAndRunPostLayoutTasks(optional Node? node = null);
255
256    [RaisesException] void forceFullRepaint(Document document);
257
258    // Returns a list of draggable/non-draggable regions in the document.
259    [RaisesException] DOMRectList draggableRegions(Document document);
260    [RaisesException] DOMRectList nonDraggableRegions(Document document);
261
262    // Returns a string with information about the mouse cursor used at the specified client location.
263    DOMString getCurrentCursorInfo();
264
265    readonly attribute boolean cursorUpdatePending;
266
267    DOMString markerTextForListItem(Element element);
268
269    [CallWith=Isolate, RaisesException] ArrayBuffer serializeObject(any obj);
270    [CallWith=Isolate] any deserializeBuffer(ArrayBuffer buffer);
271
272    void forceReload(boolean endToEnd);
273
274    DOMString getImageSourceURL(Element element);
275    [RaisesException] void forceImageReload(Element element);
276
277    DOMString selectMenuListText(HTMLSelectElement select);
278    boolean isSelectPopupVisible(Node node);
279    boolean selectPopupItemStyleIsRtl(Node select, long itemIndex);
280    long selectPopupItemStyleFontHeight(Node select, long itemIndex);
281    void resetTypeAheadSession(HTMLSelectElement select);
282
283    StaticSelection getDragCaret();
284    [RaisesException] StaticSelection getSelectionInFlatTree(Window window);
285    // TODO(editing-dev): We should change |visibleSelection*| to
286    // |StaticSelection|.
287    readonly attribute Node? visibleSelectionAnchorNode;
288    readonly attribute unsigned long visibleSelectionAnchorOffset;
289    readonly attribute Node? visibleSelectionFocusNode;
290    readonly attribute unsigned long visibleSelectionFocusOffset;
291    [RaisesException] DOMRect selectionBounds();
292    readonly attribute DOMString textAffinity;
293
294    boolean loseSharedGraphicsContext3D();
295
296    [RaisesException] void forceCompositingUpdate(Document document);
297
298    [RaisesException] void setShouldRevealPassword(Element element, boolean reveal);
299
300    [CallWith=ScriptState] Promise<any> createResolvedPromise(any value);
301    [CallWith=ScriptState] Promise<any> createRejectedPromise(any reason);
302    [CallWith=ScriptState] Promise<any> addOneToPromise(Promise<any> promise);
303    [CallWith=ScriptState, RaisesException] Promise<any> promiseCheck(long arg1, boolean arg2, object arg3, DOMString arg4, sequence<DOMString> arg5);
304    [CallWith=ScriptState] Promise<any> promiseCheckWithoutExceptionState(object arg1, DOMString arg2, DOMString... variadic);
305    [CallWith=ScriptState] Promise<any> promiseCheckRange([EnforceRange] octet arg1);
306    [CallWith=ScriptState] Promise<any> promiseCheckOverload(Location arg1);
307    [CallWith=ScriptState] Promise<any> promiseCheckOverload(Document arg1);
308    [CallWith=ScriptState] Promise<any> promiseCheckOverload(Location arg1, long arg2, long arg3);
309
310    void setValueForUser(HTMLInputElement element, DOMString value);
311
312    void setFocused(boolean focused);
313    void setInitialFocus(boolean reverse);
314
315    // When the FocuslessSpatialNavigation feature is enabled, spatial
316    // navigation moves "interest" around a page, rather than focus. This
317    // attribute returns the currently interested element on the page.
318    readonly attribute Element? interestedElement;
319
320    boolean isInCanvasFontCache(Document document, DOMString fontString);
321    unsigned long canvasFontCacheMaxFonts();
322
323    DictionaryTest dictionaryTest();
324    RecordTest recordTest();
325    SequenceTest sequenceTest();
326    UnionTypesTest unionTypesTest();
327    CallbackFunctionTest callbackFunctionTest();
328    [RaisesException] void setScrollChain(ScrollState scrollState, sequence<Element> elements);
329    void scheduleBlinkGC();
330
331    DOMString selectedHTMLForClipboard();
332    DOMString selectedTextForClipboard();
333
334    void setVisualViewportOffset(long x, long y);
335
336    boolean isUseCounted(Document document, unsigned long feature);
337    boolean isCSSPropertyUseCounted(Document document, DOMString propertyName);
338    boolean isAnimatedCSSPropertyUseCounted(Document document, DOMString propertyName);
339    void clearUseCounter(Document document, unsigned long feature);
340
341    sequence<DOMString> getCSSPropertyLonghands();
342    sequence<DOMString> getCSSPropertyShorthands();
343    sequence<DOMString> getCSSPropertyAliases();
344
345    // Returns a promise that is resolved when |feature| is counted on
346    // |document|'s UseCounter. When |feature| was already counted, it's
347    // immediately resolved.
348    [CallWith=ScriptState] Promise<boolean> observeUseCounter(Document document, unsigned long feature);
349
350    readonly attribute unsigned long length;
351    getter long (unsigned long index);
352    iterable<long>;
353
354    [Unscopable] readonly attribute DOMString unscopableAttribute;
355    [Unscopable] DOMString unscopableMethod();
356
357    void setCapsLockState(boolean enabled);
358
359    // pseudo: One of ":focus", ":focus-within", ":active", and ":hover".
360    [RaisesException] void setPseudoClassState(Element element, DOMString pseudo, boolean enabled);
361
362    // Returns whether the scrollbar was able to be shown or hidden; not all platforms
363    // support overlay scrollbars.
364    boolean setScrollbarVisibilityInScrollableArea(Node node, boolean visible);
365
366    [RaisesException] double monotonicTimeToZeroBasedDocumentTime(double platformTime);
367    long long currentTimeTicks();
368
369    DOMString getScrollAnimationState(Node node);
370
371    DOMString getProgrammaticScrollAnimationState(Node node);
372
373    DOMRect visualRect(Node node);
374
375    OriginTrialsTest originTrialsTest();
376
377    void crash();
378
379    DOMString evaluateInInspectorOverlay(DOMString script);
380
381    void setIsLowEndDevice(boolean isLowEndDevice);
382    boolean isLowEndDevice();
383
384    sequence<DOMString> supportedTextEncodingLabels();
385
386    // When RuntimeEnabledFeatures::PaintUnderInvalidationCheckingEnabled() and
387    // simulateRasterUnderInvalidation(true) is called, all changed pixels will
388    // be reported as raster under-invalidations.
389    void simulateRasterUnderInvalidations(boolean enable);
390
391    // The number of calls to update the blink lifecycle (see:
392    // LocalFrameView::UpdateLifecyclePhasesInternal).
393    unsigned long LifecycleUpdateCount();
394
395    // Disable the 'delay' option for IntersectionObserver, so that observations
396    // are recomputed on every frame.  This eliminates the need to add
397    // setTimeout(..., delay_ms) calls to web tests to wait for notifications
398    // to be generated.
399    void DisableIntersectionObserverThrottleDelay();
400
401    // Reports whether an iframe's browsing context runs in a separate process
402    boolean isSiteIsolated(HTMLIFrameElement iframe);
403
404    // Reports whether a parent document is propagating occlusion information
405    // down to a child frame, for the purpose of servicing IntersectionObserver
406    // instances that track visibility.
407    boolean isTrackingOcclusionForIFrame(HTMLIFrameElement iframe);
408
409    // Declare that the given |name| is in use by the embedder via the custom
410    // element mechanism.
411    [RaisesException] void addEmbedderCustomElementName(DOMString name);
412
413    // https://html.spec.whatwg.org/C/#resolve-a-module-specifier
414    // Throws TypeError on error.
415    // Used for testing Import Maps https://github.com/domenic/import-maps
416    [RaisesException] DOMString resolveModuleSpecifier(DOMString specifier, DOMString base_url, Document document);
417
418    // Returns the current serialized import map of the Document.
419    // TODO(crbug.com/927181): Currently this returns the "imports" value,
420    // because Blink doesn't support scopes yet. Update this once scopes are
421    // implemented.
422    [RaisesException] DOMString getParsedImportMap(Document document);
423
424    // Sets the scale for devtools device emulation.
425    [RaisesException] void setDeviceEmulationScale(float scale);
426
427    // Return a string that identifies |window|'s WindowAgent. You can use it
428    // to distinguish different Agent instances (perhaps in a remote process).
429    // The returned string is composed of the process ID and the memory address
430    // of the Agent object.
431    DOMString getAgentId(Window window);
432
433    void useMockOverlayScrollbars();
434    readonly attribute boolean overlayScrollbarsEnabled;
435
436    // Request generation of a Reporting report.
437    void generateTestReport(DOMString message);
438};
439