chromium/src/third_party/blink/public/mojom/remote_objects/remote_objects.mojom

// Copyright 2018 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module blink.mojom;

import "mojo/public/mojom/base/big_buffer.mojom";
import "mojo/public/mojom/base/string16.mojom";

// These interfaces allow an object implemented outside the Blink renderer
// process to be exposed to JavaScript via synchronous IPC.
//
// See also this design doc:
//   https://docs.google.com/document/d/1T8Zj_gZK7jHsy80Etk-Rw4hXMIW4QeaTtXjy5ZKP3X0/edit

// Implemented in the process hosting the remote objects.
// Allows access to an object graph.
//
// Identifiers used by this object apply only within this RemoteObjectHost.
interface RemoteObjectHost {
  // Binds |receiver| to an implementation of RemoteObject corresponding to
  // |object_id|.
  GetObject(int32 object_id, pending_receiver<RemoteObject> receiver);

  // Increase the object's reference count when the named object is injected to JS.
  AcquireObject(int32 object_id);

  // Ideally lifetime would be scoped to an associated RemoteObject pipe. This
  // is complicated by the fact that the missing support for associated
  // interfaces in the Mojo Java bindings.
  ReleaseObject(int32 object_id);
};

// Implemented in the process hosting the remote object.
// Allows methods to be synchronously invoked on the object.
interface RemoteObject {
  [Sync] HasMethod(string name) => (bool method_exists);
  [Sync] GetMethods() => (array<string> method_names);
  [Sync] InvokeMethod(string name, array<RemoteInvocationArgument> arguments)
      => (RemoteInvocationResult result);

  // Notifies ReleaseObject is called by RemoteObjectHost interface to ensure
  // the object's unreference when the pipe is closed.
  NotifyReleasedObject();
};

// Implemented in the renderer.
interface RemoteObjectGatewayFactory {
  // Creates an implementation of RemoteObjectGateway associated with |host|
  // and binds it to |gateway|.
  CreateRemoteObjectGateway(pending_remote<RemoteObjectHost> host,
                            pending_receiver<RemoteObjectGateway> gateway);
};

// Implemented in the renderer.
interface RemoteObjectGateway {
  // Exposes object with |name| and |id| to the frame.
  AddNamedObject(string name, int32 object_id);

  // Removes object with |name| from the frame context.
  RemoveNamedObject(string name);
};

enum SingletonJavaScriptValue {
  kNull,
  kUndefined,
};

enum RemoteArrayType {
  kInt8Array = 1,
  kUint8Array,
  kInt16Array,
  kUint16Array,
  kInt32Array,
  kUint32Array,
  kFloat32Array,
  kFloat64Array,
};

struct RemoteTypedArray {
  RemoteArrayType type;
  mojo_base.mojom.BigBuffer buffer;
};

union RemoteInvocationArgument {
  double number_value;
  bool boolean_value;
  mojo_base.mojom.String16 string_value;
  SingletonJavaScriptValue singleton_value;
  array<RemoteInvocationArgument> array_value;
  RemoteTypedArray typed_array_value;
  int32 object_id_value;
};

enum RemoteInvocationError {
  OK = 0,
  METHOD_NOT_FOUND,
  OBJECT_GET_CLASS_BLOCKED,
  EXCEPTION_THROWN,
  NON_ASSIGNABLE_TYPES,
};

union RemoteInvocationResultValue {
  double number_value;
  bool boolean_value;
  mojo_base.mojom.String16 string_value;
  SingletonJavaScriptValue singleton_value;

  // Scoped to the RemoteObjectHost that manages the callee object.
  // The caller is expected to use RemoteObjectHost.GetObject to obtain a pipe,
  // if it does not already have one.
  int32 object_id;
};

struct RemoteInvocationResult {
  RemoteInvocationError error = OK;

  // Must be set if |error == OK|.
  RemoteInvocationResultValue? value;
};