SavedFrameAPI.h (6198B)
1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2 /* This Source Code Form is subject to the terms of the Mozilla Public 3 * License, v. 2.0. If a copy of the MPL was not distributed with this 4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 5 6 /* 7 * Functions and types related to SavedFrame objects created by the Debugger 8 * API. 9 */ 10 11 #ifndef js_SavedFrameAPI_h 12 #define js_SavedFrameAPI_h 13 14 #include "jstypes.h" // JS_PUBLIC_API 15 16 #include "js/ColumnNumber.h" // JS::TaggedColumnNumberOneOrigin 17 #include "js/TypeDecls.h" 18 19 struct JSPrincipals; 20 21 namespace JS { 22 23 /* 24 * Accessors for working with SavedFrame JSObjects 25 * 26 * Each of these functions assert that if their `HandleObject savedFrame` 27 * argument is non-null, its JSClass is the SavedFrame class (or it is a 28 * cross-compartment or Xray wrapper around an object with the SavedFrame class) 29 * and the object is not the SavedFrame.prototype object. 30 * 31 * Each of these functions will find the first SavedFrame object in the chain 32 * whose underlying stack frame principals are subsumed by the given 33 * |principals|, and operate on that SavedFrame object. This prevents leaking 34 * information about privileged frames to un-privileged callers 35 * 36 * The SavedFrame in parameters do _NOT_ need to be in the same compartment as 37 * the cx, and the various out parameters are _NOT_ guaranteed to be in the same 38 * compartment as cx. 39 * 40 * You may consider or skip over self-hosted frames by passing 41 * `SavedFrameSelfHosted::Include` or `SavedFrameSelfHosted::Exclude` 42 * respectively. 43 * 44 * Additionally, it may be the case that there is no such SavedFrame object 45 * whose captured frame's principals are subsumed by |principals|! If the 46 * `HandleObject savedFrame` argument is null, or the |principals| do not 47 * subsume any of the chained SavedFrame object's principals, 48 * `SavedFrameResult::AccessDenied` is returned and a (hopefully) sane default 49 * value is chosen for the out param. 50 * 51 * See also `js/src/doc/SavedFrame/SavedFrame.md`. 52 */ 53 54 enum class SavedFrameResult { Ok, AccessDenied }; 55 56 enum class SavedFrameSelfHosted { Include, Exclude }; 57 58 /** 59 * Given a SavedFrame JSObject, get its source property. Defaults to the empty 60 * string. 61 */ 62 extern JS_PUBLIC_API SavedFrameResult GetSavedFrameSource( 63 JSContext* cx, JSPrincipals* principals, Handle<JSObject*> savedFrame, 64 MutableHandle<JSString*> sourcep, 65 SavedFrameSelfHosted selfHosted = SavedFrameSelfHosted::Include); 66 67 /** 68 * Given a SavedFrame JSObject, get an ID identifying its ScriptSource. 69 * Defaults to 0. 70 */ 71 extern JS_PUBLIC_API SavedFrameResult GetSavedFrameSourceId( 72 JSContext* cx, JSPrincipals* principals, Handle<JSObject*> savedFrame, 73 uint32_t* sourceIdp, 74 SavedFrameSelfHosted selfHosted = SavedFrameSelfHosted::Include); 75 76 /** 77 * Given a SavedFrame JSObject, get its line property (1-origin). 78 * Defaults to 0. 79 */ 80 extern JS_PUBLIC_API SavedFrameResult GetSavedFrameLine( 81 JSContext* cx, JSPrincipals* principals, Handle<JSObject*> savedFrame, 82 uint32_t* linep, 83 SavedFrameSelfHosted selfHosted = SavedFrameSelfHosted::Include); 84 85 /** 86 * Given a SavedFrame JSObject, get its column property. Defaults to 0. 87 */ 88 extern JS_PUBLIC_API SavedFrameResult GetSavedFrameColumn( 89 JSContext* cx, JSPrincipals* principals, Handle<JSObject*> savedFrame, 90 JS::TaggedColumnNumberOneOrigin* columnp, 91 SavedFrameSelfHosted selfHosted = SavedFrameSelfHosted::Include); 92 93 /** 94 * Given a SavedFrame JSObject, get its functionDisplayName string, or nullptr 95 * if SpiderMonkey was unable to infer a name for the captured frame's 96 * function. Defaults to nullptr. 97 */ 98 extern JS_PUBLIC_API SavedFrameResult GetSavedFrameFunctionDisplayName( 99 JSContext* cx, JSPrincipals* principals, Handle<JSObject*> savedFrame, 100 MutableHandle<JSString*> namep, 101 SavedFrameSelfHosted selfHosted = SavedFrameSelfHosted::Include); 102 103 /** 104 * Given a SavedFrame JSObject, get its asyncCause string. Defaults to nullptr. 105 */ 106 extern JS_PUBLIC_API SavedFrameResult GetSavedFrameAsyncCause( 107 JSContext* cx, JSPrincipals* principals, Handle<JSObject*> savedFrame, 108 MutableHandle<JSString*> asyncCausep, 109 SavedFrameSelfHosted selfHosted = SavedFrameSelfHosted::Include); 110 111 /** 112 * Given a SavedFrame JSObject, get its asyncParent SavedFrame object or nullptr 113 * if there is no asyncParent. The `asyncParentp` out parameter is _NOT_ 114 * guaranteed to be in the cx's compartment. Defaults to nullptr. 115 */ 116 extern JS_PUBLIC_API SavedFrameResult GetSavedFrameAsyncParent( 117 JSContext* cx, JSPrincipals* principals, Handle<JSObject*> savedFrame, 118 MutableHandle<JSObject*> asyncParentp, 119 SavedFrameSelfHosted selfHosted = SavedFrameSelfHosted::Include); 120 121 /** 122 * Given a SavedFrame JSObject, get its parent SavedFrame object or nullptr if 123 * it is the oldest frame in the stack. The `parentp` out parameter is _NOT_ 124 * guaranteed to be in the cx's compartment. Defaults to nullptr. 125 */ 126 extern JS_PUBLIC_API SavedFrameResult GetSavedFrameParent( 127 JSContext* cx, JSPrincipals* principals, Handle<JSObject*> savedFrame, 128 MutableHandle<JSObject*> parentp, 129 SavedFrameSelfHosted selfHosted = SavedFrameSelfHosted::Include); 130 131 /** 132 * Given a SavedFrame object, convert it and its transitive parents to plain 133 * objects. Because SavedFrame objects store their properties on the prototype, 134 * they cannot be usefully stringified to JSON. Assigning their properties to 135 * plain objects allow those objects to be stringified and the saved frame stack 136 * can be encoded as a string. 137 */ 138 JS_PUBLIC_API JSObject* ConvertSavedFrameToPlainObject( 139 JSContext* cx, JS::HandleObject savedFrame, 140 JS::SavedFrameSelfHosted selfHosted); 141 142 } // namespace JS 143 144 namespace js { 145 146 /** 147 * Get the first SavedFrame object in this SavedFrame stack whose principals are 148 * subsumed by the given |principals|. If there is no such frame, return 149 * nullptr. 150 * 151 * Do NOT pass a non-SavedFrame object here. 152 */ 153 extern JS_PUBLIC_API JSObject* GetFirstSubsumedSavedFrame( 154 JSContext* cx, JSPrincipals* principals, JS::Handle<JSObject*> savedFrame, 155 JS::SavedFrameSelfHosted selfHosted); 156 157 } // namespace js 158 159 #endif /* js_SavedFrameAPI_h */