NetSurf
js.h
Go to the documentation of this file.
1/*
2 * Copyright 2012 Vincent Sanders <vince@netsurf-browser.org>
3 *
4 * This file is part of NetSurf, http://www.netsurf-browser.org/
5 *
6 * NetSurf is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; version 2 of the License.
9 *
10 * NetSurf is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License
16 * along with this program. If not, see <http://www.gnu.org/licenses/>.
17 */
18
19/** \file
20 * Interface to javascript engine functions.
21 */
22
23#ifndef NETSURF_JAVASCRIPT_JS_H_
24#define NETSURF_JAVASCRIPT_JS_H_
25
26#include "utils/errors.h"
27
28struct dom_event;
29struct dom_document;
30struct dom_node;
31struct dom_element;
32struct dom_string;
33
34/**
35 * JavaScript interpreter heap
36 *
37 * In order to try and be moderately performant, we create a heap
38 * per browser window. This heap is shared by all browsing contexts
39 * we end up creating in that window.
40 */
41typedef struct jsheap jsheap;
42
43/**
44 * JavaScript interpreter thread
45 *
46 * When we create a browsing context itself (window+content) we have
47 * to create a JS thread to attach to the browsing context.
48 *
49 * JS threads are associated with heaps and will be destroyed when
50 * the heap is destroyed. They can be shut down manually though
51 * and should be for object lifetime safety reasons.
52 */
53typedef struct jsthread jsthread;
54
55/**
56 * Initialise javascript interpreter
57 */
58void js_initialise(void);
59
60/**
61 * finalise javascript interpreter
62 */
63void js_finalise(void);
64
65/**
66 * Create a new javascript heap.
67 *
68 * There is usually one heap per browser window.
69 *
70 * \param timeout elapsed wallclock time (in seconds) before \a callback is called
71 * \param heap Updated to the created JS heap
72 * \return NSERROR_OK on success, appropriate error otherwise.
73 */
74nserror js_newheap(int timeout, jsheap **heap);
75
76/**
77 * Destroy a previously created heap.
78 *
79 * \param heap The heap to destroy
80 */
82
83/**
84 * Create a new javascript thread
85 *
86 * This is called once for a page with javascript script tags on
87 * it. It constructs a fresh global window object and prepares the JS
88 * browsing context. It's important that threads are shut down cleanly
89 * when the browsing context is going to be cleaned up.
90 *
91 * \param heap The heap to create the thread within
92 * \param win_priv The value to give to the Window constructor as the window
93 * \param doc_priv The value to give to the Document constructor as the document
94 * \param thread Updated to the created thread
95 * \return NSERROR_OK on success, appropriate error otherwise
96 */
97nserror js_newthread(jsheap *heap, void *win_priv, void *doc_priv, jsthread **thread);
98
99/**
100 * Close a javascript thread
101 *
102 * This should be called when the HTML content which owns the thread is
103 * being closed. This is a separate process from destroying the thread
104 * and merely disconnects any callbacks and thus hopefully stops
105 * additional JS things from triggering. If any code runs and attempts to
106 * register callbacks after closedown, they will fail.
107 *
108 * \param thread The thread to close down
109 * \return NSERROR_OK on success, appropriate error otherwise
110 */
112
113/**
114 * Destroy a javascript thread
115 *
116 * This should be called when the browsing context is done with the thread.
117 *
118 * This will be called when the HTML content associated with the browsing
119 * context is being destroyed. The thread should have already been closed
120 * down during the HTML content close.
121 *
122 * \param thread The thread to be destroyed
123 */
124void js_destroythread(jsthread *thread);
125
126/**
127 * execute some javascript in a context
128 */
129bool js_exec(jsthread *thread, const uint8_t *txt, size_t txtlen, const char *name);
130
131/**
132 * fire an event at a dom node
133 */
134bool js_fire_event(jsthread *thread, const char *type, struct dom_document *doc, struct dom_node *target);
135
136bool
138 struct dom_document *document,
139 struct dom_node *node,
140 struct dom_string *event_type_dom,
141 void *js_funcval);
142
143/*** New Events ***/
144
145/**
146 * Handle a new element being created.
147 *
148 * This is called once an element is inserted into the DOM document handled
149 * by the context provided. The JS implementation must then scan the element
150 * for on* attributes and register appropriate listeners for those handlers.
151 */
152void js_handle_new_element(jsthread *thread, struct dom_element *node);
153
154/**
155 * Handle an event propagation finished callback.
156 *
157 * This is called once an event finishes propagating, no matter how it
158 * finishes. The intent here is that the JS context can perform any cleanups
159 * it may need to perform before the DOM finishes and the event may end up
160 * freed.
161 */
162void js_event_cleanup(jsthread *thread, struct dom_event *evt);
163
164#endif /* NETSURF_JAVASCRIPT_JS_H_ */
Error codes.
nserror
Enumeration of error codes.
Definition: errors.h:29
const char * type
Definition: filetype.cpp:44
void js_destroythread(jsthread *thread)
Destroy a javascript thread.
Definition: dukky.c:815
void js_destroyheap(jsheap *heap)
Destroy a previously created heap.
Definition: dukky.c:638
void js_handle_new_element(jsthread *thread, struct dom_element *node)
Handle a new element being created.
Definition: dukky.c:1471
void js_event_cleanup(jsthread *thread, struct dom_event *evt)
Handle an event propagation finished callback.
Definition: dukky.c:1551
void js_finalise(void)
finalise javascript interpreter
Definition: dukky.c:590
nserror js_newheap(int timeout, jsheap **heap)
Create a new javascript heap.
Definition: dukky.c:598
nserror js_newthread(jsheap *heap, void *win_priv, void *doc_priv, jsthread **thread)
Create a new javascript thread.
Definition: dukky.c:650
void js_initialise(void)
Initialise javascript interpreter.
Definition: dukky.c:577
bool js_fire_event(jsthread *thread, const char *type, struct dom_document *doc, struct dom_node *target)
fire an event at a dom node
Definition: dukky.c:1567
bool js_dom_event_add_listener(jsthread *thread, struct dom_document *document, struct dom_node *node, struct dom_string *event_type_dom, void *js_funcval)
bool js_exec(jsthread *thread, const uint8_t *txt, size_t txtlen, const char *name)
execute some javascript in a context
Definition: dukky.c:922
nserror js_closethread(jsthread *thread)
Close a javascript thread.
Definition: dukky.c:761
dukky javascript heap
Definition: dukky.c:59
dukky javascript thread
Definition: dukky.c:70
jsheap * heap
The heap this thread belongs to.
Definition: dukky.c:73