bundles/org.eclipse.swt.win32.win32.x86_64/src/org/eclipse/swt/browser/BrowserFunction.java

   1 /*******************************************************************************
   2  * Copyright (c) 2008, 2018 IBM Corporation and others.
   3  *
   4  * This program and the accompanying materials
   5  * are made available under the terms of the Eclipse Public License 2.0
   6  * which accompanies this distribution, and is available at
   7  * https://www.eclipse.org/legal/epl-2.0/
   8  *
   9  * SPDX-License-Identifier: EPL-2.0
  10  *
  11  * Contributors:
  12  *     IBM Corporation - initial API and implementation
  13  *******************************************************************************/
  14 package org.eclipse.swt.browser;
  15
  16 import java.util.*;
  17
  18 import org.eclipse.swt.*;
  19
  20 /**
  21  * Instances of this class represent java-side "functions" that
  22  * are invokable from javascript.  Browser clients define these
  23  * functions by subclassing <code>BrowserFunction</code> and
  24  * overriding its <code>function(Object[])</code> method.  This
  25  * method will be invoked whenever javascript running in the
  26  * Browser makes a call with the function's name.
  27  *
  28  * <p>
  29  * Application code must explicitly invoke the
  30  * <code>BrowserFunction.dispose()</code> method to release the
  31  * resources managed by each instance when those instances are no
  32  * longer required.  Since there is usually a correlation between
  33  * the registering of BrowserFunction(s) in a Browser and the
  34  * loading of a page in the Browser that is aware of these
  35  * functions, the <code>LocationListener.changed()</code> listener
  36  * is often a good place to do this.
  37  * </p><p>
  38  * Note that disposing a Browser automatically disposes all
  39  * BrowserFunctions associated with it.
  40  * </p>
  41  *
  42  * @see #dispose()
  43  * @see #function(Object[])
  44  * @see org.eclipse.swt.browser.LocationListener#changed(LocationEvent)
  45  *
  46  * @since 3.5
  47  */
  48 public class BrowserFunction {
  49         Browser browser;
  50         String name;
  51         String functionString;
  52         int index;
  53         boolean isEvaluate, top;
  54         String token;
  55         String[] frameNames;
  56
  57 /**
  58  * Constructs a new instance of this class, which will be invokable
  59  * by javascript running in the specified Browser.  The function will
  60  * be accessible in the top-level window and all child frames.  To
  61  * create a function with a reduced scope of accessibility use the
  62  * <code>BrowserFunction</code> constructor that accepts frame names
  63  * instead.
  64  * <p>
  65  * You must dispose the BrowserFunction when it is no longer required.
  66  * A common place to do this is in a <code>LocationListener.changed()</code>
  67  * listener.
  68  * </p>
  69  * @param browser the browser whose javascript can invoke this function
  70  * @param name the name that javascript will use to invoke this function
  71  *
  72  * @exception IllegalArgumentException <ul>
  73  *    <li>ERROR_NULL_ARGUMENT - if the browser is null</li>
  74  *    <li>ERROR_NULL_ARGUMENT - if the name is null</li>
  75  * </ul>
  76  *
  77  * @exception SWTException <ul>
  78  *    <li>ERROR_WIDGET_DISPOSED - if the browser has been disposed</li>
  79  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  80  * </ul>
  81  *
  82  * @see #dispose()
  83  * @see #BrowserFunction(Browser, String, boolean, String[])
  84  * @see org.eclipse.swt.browser.LocationListener#changed(LocationEvent)
  85  */
  86 public BrowserFunction (Browser browser, String name) {
  87         this (browser, name, true, null, true);
  88 }
  89
  90 /**
  91  * Constructs a new instance of this class, which will be invokable
  92  * by javascript running in the specified Browser.  The accessibility
  93  * of the function to the top-level window and its child frames is
  94  * determined by the <code>top</code> and <code>frameNames</code>
  95  * arguments.  To create a function that is globally accessible to
  96  * the top-level window and all child frames use the
  97  * <code>BrowserFunction</code> constructor that does not accept frame
  98  * names instead.
  99  * <p>
 100  * You must dispose the BrowserFunction when it is no longer required.
 101  * A common place to do this is in a <code>LocationListener.changed()</code>
 102  * listener.
 103  * </p>
 104  * @param browser the browser whose javascript can invoke this function
 105  * @param name the name that javascript will use to invoke this function
 106  * @param top <code>true</code> if the function should be accessible to the
 107  * top-level window and <code>false</code> otherwise
 108  * @param frameNames the names of the child frames that the function should
 109  * be accessible in
 110  *
 111  * @exception IllegalArgumentException <ul>
 112  *    <li>ERROR_NULL_ARGUMENT - if the browser is null</li>
 113  *    <li>ERROR_NULL_ARGUMENT - if the name is null</li>
 114  * </ul>
 115  *
 116  * @exception SWTException <ul>
 117  *    <li>ERROR_WIDGET_DISPOSED - if the browser has been disposed</li>
 118  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
 119  * </ul>
 120  *
 121  * @see #dispose()
 122  * @see #BrowserFunction(Browser, String)
 123  * @see org.eclipse.swt.browser.LocationListener#changed(LocationEvent)
 124  *
 125  * @since 3.8
 126  */
 127 public BrowserFunction (Browser browser, String name, boolean top, String[] frameNames) {
 128         this (browser, name, top, frameNames, true);
 129 }
 130
 131 BrowserFunction (Browser browser, String name, boolean top, String[] frameNames, boolean create) {
 132         super ();
 133         if (browser == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
 134         if (name == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
 135         if (browser.isDisposed ()) SWT.error (SWT.ERROR_WIDGET_DISPOSED);
 136         browser.checkWidget ();
 137         this.browser = browser;
 138         this.name = name;
 139         this.top = top;
 140         this.frameNames = frameNames;
 141
 142         Random random = new Random ();
 143         byte[] bytes = new byte[16];
 144         random.nextBytes (bytes);
 145         StringBuilder buffer = new StringBuilder ();
 146         for (int i = 0; i < bytes.length; i++) {
 147                 buffer.append (Integer.toHexString (bytes[i] & 0xff));
 148         }
 149         token = buffer.toString ();
 150         if (create) browser.webBrowser.createFunction (this);
 151 }
 152
 153 /**
 154  * Disposes of the resources associated with this BrowserFunction.
 155  * Applications must dispose of all BrowserFunctions that they create.
 156  * <p>
 157  * Note that disposing a Browser automatically disposes all
 158  * BrowserFunctions associated with it.
 159  * </p>
 160  */
 161 public void dispose () {
 162         dispose (true);
 163 }
 164
 165 void dispose (boolean remove) {
 166         if (index < 0) return;
 167         if (remove) browser.webBrowser.destroyFunction (this);
 168         browser = null;
 169         name = functionString = null;
 170         index = -1;
 171 }
 172
 173 /**
 174  * Subclasses should override this method.  This method is invoked when
 175  * the receiver's function is called from javascript.  If all of the
 176  * arguments that are passed to the javascript function call are of
 177  * supported types then this method is invoked with the argument values
 178  * converted as follows:
 179  *
 180  * javascript null or undefined -&gt; <code>null</code>
 181  * javascript number -&gt; <code>java.lang.Double</code>
 182  * javascript string -&gt; <code>java.lang.String</code>
 183  * javascript boolean -&gt; <code>java.lang.Boolean</code>
 184  * javascript array whose elements are all of supported types -&gt; <code>java.lang.Object[]</code>
 185  *
 186  * If any of the javascript arguments are of unsupported types then the
 187  * function invocation will fail and this method will not be called.
 188  *
 189  * This method must return a value with one of these supported java types to
 190  * the javascript caller.  Note that <code>null</code> values are converted
 191  * to javascript's <code>null</code> value (not <code>undefined</code>), and
 192  * instances of any <code>java.lang.Number</code> subclass will be converted
 193  * to a javascript number.
 194  *
 195  * @param arguments the javascript arguments converted to java equivalents
 196  * @return the value to return to the javascript caller
 197  *
 198  * @exception SWTException <ul>
 199  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
 200  *    <li>ERROR_FUNCTION_DISPOSED when the BrowserFunction has been disposed</li>
 201  * </ul>
 202  */
 203 public Object function (Object[] arguments) {
 204         if (index < 0) SWT.error (SWT.ERROR_FUNCTION_DISPOSED);
 205         browser.checkWidget ();
 206         return null;
 207 }
 208
 209 /**
 210  * Returns the Browser whose pages can invoke this BrowserFunction.
 211  *
 212  * @return the Browser associated with this BrowserFunction
 213  *
 214  * @exception SWTException <ul>
 215  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
 216  *    <li>ERROR_FUNCTION_DISPOSED when the BrowserFunction has been disposed</li>
 217  * </ul>
 218  */
 219 public Browser getBrowser () {
 220         if (index < 0) SWT.error (SWT.ERROR_FUNCTION_DISPOSED);
 221         browser.checkWidget ();
 222         return browser;
 223 }
 224
 225 /**
 226  * Returns the name that javascript can use to invoke this BrowserFunction.
 227  *
 228  * @return the BrowserFunction's name
 229  *
 230  * @exception SWTException <ul>
 231  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
 232  *    <li>ERROR_FUNCTION_DISPOSED when the BrowserFunction has been disposed</li>
 233  * </ul>
 234  */
 235 public String getName () {
 236         if (index < 0) SWT.error (SWT.ERROR_FUNCTION_DISPOSED);
 237         browser.checkWidget ();
 238         return name;
 239 }
 240
 241 /**
 242  * Returns <code>true</code> if this BrowserFunction has been disposed
 243  * and <code>false</code> otherwise.
 244  * <p>
 245  * This method gets the dispose state for the BrowserFunction.
 246  * When a BrowserFunction has been disposed it is an error to
 247  * invoke any of its methods.
 248  * </p><p>
 249  * Note that disposing a Browser automatically disposes all
 250  * BrowserFunctions associated with it.
 251  * </p>
 252  * @return <code>true</code> if this BrowserFunction has been disposed
 253  * and <code>false</code> otherwise
 254  */
 255 public boolean isDisposed () {
 256         return index < 0;
 257 }
 258 }