1// Copyright 2014 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5/**
6 * @fileoverview
7 * Interface abstracting the ClientPlugin functionality.
8 */
9
10'use strict';
11
12/** @suppress {duplicate} */
13var remoting = remoting || {};
14
15/**
16 * @interface
17 * @extends {base.Disposable}
18 */
19remoting.ClientPlugin = function() {};
20
21/**
22 * @return {number} The width of the remote desktop, in pixels.
23 */
24remoting.ClientPlugin.prototype.getDesktopWidth = function() {};
25
26/**
27 * @return {number} The height of the remote desktop, in pixels.
28 */
29remoting.ClientPlugin.prototype.getDesktopHeight = function() {};
30
31/**
32 * @return {number} The x-DPI of the remote desktop.
33 */
34remoting.ClientPlugin.prototype.getDesktopXDpi = function() {};
35
36/**
37 * @return {number} The y-DPI of the remote desktop.
38 */
39remoting.ClientPlugin.prototype.getDesktopYDpi = function() {};
40
41/**
42 * @return {HTMLElement} The DOM element representing the remote session.
43 */
44remoting.ClientPlugin.prototype.element = function() {};
45
46/**
47 * @param {function():void} onDone Completion callback.
48 */
49remoting.ClientPlugin.prototype.initialize = function(onDone) {};
50
51/**
52 * @param {string} hostJid The jid of the host to connect to.
53 * @param {string} hostPublicKey The base64 encoded version of the host's
54 *     public key.
55 * @param {string} localJid Local jid.
56 * @param {string} sharedSecret The access code for IT2Me or the PIN
57 *     for Me2Me.
58 * @param {string} authenticationMethods Comma-separated list of
59 *     authentication methods the client should attempt to use.
60 * @param {string} authenticationTag A host-specific tag to mix into
61 *     authentication hashes.
62 * @param {string} clientPairingId For paired Me2Me connections, the
63 *     pairing id for this client, as issued by the host.
64 * @param {string} clientPairedSecret For paired Me2Me connections, the
65 *     paired secret for this client, as issued by the host.
66 */
67remoting.ClientPlugin.prototype.connect = function(
68    hostJid, hostPublicKey, localJid, sharedSecret,
69    authenticationMethods, authenticationTag,
70    clientPairingId, clientPairedSecret) {};
71
72/**
73 * @param {number} key The keycode to inject.
74 * @param {boolean} down True for press; false for a release.
75 */
76remoting.ClientPlugin.prototype.injectKeyEvent =
77    function(key, down) {};
78
79/**
80 * @param {number} from
81 * @param {number} to
82 */
83remoting.ClientPlugin.prototype.remapKey = function(from, to) {};
84
85/**
86 * Release all keys currently being pressed.
87 */
88remoting.ClientPlugin.prototype.releaseAllKeys = function() {};
89
90/**
91 * @param {number} width
92 * @param {number} height
93 * @param {number} dpi
94 */
95remoting.ClientPlugin.prototype.notifyClientResolution =
96    function(width, height, dpi) {};
97
98/**
99 * @param {string} iq
100 */
101remoting.ClientPlugin.prototype.onIncomingIq = function(iq) {};
102
103/**
104 * @return {boolean} True if the web-app and plugin are compatible.
105 */
106remoting.ClientPlugin.prototype.isSupportedVersion = function() {};
107
108/**
109 * @param {remoting.ClientPlugin.Feature} feature
110 * @return {boolean} True if the plugin support the specified feature.
111 */
112remoting.ClientPlugin.prototype.hasFeature = function(feature) {};
113
114/**
115 * Enable MediaSource rendering via the specified renderer.
116 *
117 * @param {remoting.MediaSourceRenderer} mediaSourceRenderer
118 */
119remoting.ClientPlugin.prototype.enableMediaSourceRendering =
120    function(mediaSourceRenderer) {};
121
122/**
123 * Sends a clipboard item to the host.
124 *
125 * @param {string} mimeType The MIME type of the clipboard item.
126 * @param {string} item The clipboard item.
127 */
128remoting.ClientPlugin.prototype.sendClipboardItem =
129    function(mimeType, item) {};
130
131/**
132 * Tell the plugin to request a PIN asynchronously.
133 */
134remoting.ClientPlugin.prototype.useAsyncPinDialog = function() {};
135
136/**
137 * Request that this client be paired with the current host.
138 *
139 * @param {string} clientName The human-readable name of the client.
140 * @param {function(string, string):void} onDone Callback to receive the
141 *     client id and shared secret when they are available.
142 */
143remoting.ClientPlugin.prototype.requestPairing =
144    function(clientName, onDone) {};
145
146/**
147 * Called when a PIN is obtained from the user.
148 *
149 * @param {string} pin The PIN.
150 */
151remoting.ClientPlugin.prototype.onPinFetched = function(pin) {};
152
153/**
154 * Sets the third party authentication token and shared secret.
155 *
156 * @param {string} token The token received from the token URL.
157 * @param {string} sharedSecret Shared secret received from the token URL.
158 */
159remoting.ClientPlugin.prototype.onThirdPartyTokenFetched =
160    function(token, sharedSecret) {};
161
162/**
163 * @param {boolean} pause True to pause the audio stream; false to resume it.
164 */
165remoting.ClientPlugin.prototype.pauseAudio = function(pause) {};
166
167/**
168 * @param {boolean} pause True to pause the video stream; false to resume it.
169 */
170remoting.ClientPlugin.prototype.pauseVideo = function(pause) {};
171
172/**
173 * @return {remoting.ClientSession.PerfStats} A summary of the connection
174 *     performance.
175 */
176remoting.ClientPlugin.prototype.getPerfStats = function() {};
177
178/**
179 * Send an extension message to the host.
180 *
181 * @param {string} name
182 * @param {string} data
183 */
184remoting.ClientPlugin.prototype.sendClientMessage =
185    function(name, data) {};
186
187/**
188 * @param {function(string):void} handler Callback for sending an IQ stanza.
189 */
190remoting.ClientPlugin.prototype.setOnOutgoingIqHandler =
191    function(handler) {};
192
193/**
194 * @param {function(string):void} handler Callback for logging debug messages.
195 */
196remoting.ClientPlugin.prototype.setOnDebugMessageHandler =
197    function(handler) {};
198
199/**
200 * @param {function(number, number):void} handler Callback for connection status
201 *     update notifications. The first parameter is the connection state; the
202 *     second is the error code, if any.
203 */
204remoting.ClientPlugin.prototype.setConnectionStatusUpdateHandler =
205    function(handler) {};
206
207/**
208 * @param {function(boolean):void} handler Callback for connection readiness
209 *     notifications.
210 */
211remoting.ClientPlugin.prototype.setConnectionReadyHandler =
212    function(handler) {};
213
214/**
215 * @param {function():void} handler Callback for desktop size change
216 *     notifications.
217 */
218remoting.ClientPlugin.prototype.setDesktopSizeUpdateHandler =
219    function(handler) {};
220
221/**
222 * @param {function(!Array.<string>):void} handler Callback to inform of
223 *     capabilities negotiated between host and client.
224 */
225remoting.ClientPlugin.prototype.setCapabilitiesHandler =
226    function(handler) {};
227
228/**
229 * @param {function(string):void} handler Callback for processing security key
230 *     (Gnubby) protocol messages.
231 */
232remoting.ClientPlugin.prototype.setGnubbyAuthHandler =
233    function(handler) {};
234
235/**
236 * @param {function(string):void} handler Callback for processing Cast protocol
237 *     messages.
238 */
239remoting.ClientPlugin.prototype.setCastExtensionHandler =
240    function(handler) {};
241
242/**
243 * @param {function(string, number, number):void} handler Callback for
244 *     processing large mouse cursor images. The first parameter is a data:
245 *     URL encoding the mouse cursor; the second and third parameters are
246 *     the cursor hotspot's x- and y-coordinates, respectively.
247 */
248remoting.ClientPlugin.prototype.setMouseCursorHandler =
249    function(handler) {};
250
251/**
252 * @param {function(string, string, string):void} handler Callback for
253 *     fetching third-party tokens. The first parameter is the token URL; the
254 *     second is the public key of the host; the third is the OAuth2 scope
255 *     being requested.
256 */
257remoting.ClientPlugin.prototype.setFetchThirdPartyTokenHandler =
258    function(handler) {};
259
260/**
261 * @param {function(boolean):void} handler Callback for fetching a PIN from
262 *     the user. The parameter is true if PIN pairing is supported by the
263 *     host, or false otherwise.
264 */
265remoting.ClientPlugin.prototype.setFetchPinHandler =
266    function(handler) {};
267
268
269/**
270 * Set of features for which hasFeature() can be used to test.
271 *
272 * @enum {string}
273 */
274remoting.ClientPlugin.Feature = {
275  INJECT_KEY_EVENT: 'injectKeyEvent',
276  NOTIFY_CLIENT_RESOLUTION: 'notifyClientResolution',
277  ASYNC_PIN: 'asyncPin',
278  PAUSE_VIDEO: 'pauseVideo',
279  PAUSE_AUDIO: 'pauseAudio',
280  REMAP_KEY: 'remapKey',
281  SEND_CLIPBOARD_ITEM: 'sendClipboardItem',
282  THIRD_PARTY_AUTH: 'thirdPartyAuth',
283  TRAP_KEY: 'trapKey',
284  PINLESS_AUTH: 'pinlessAuth',
285  EXTENSION_MESSAGE: 'extensionMessage',
286  MEDIA_SOURCE_RENDERING: 'mediaSourceRendering',
287  VIDEO_CONTROL: 'videoControl'
288};
289
290
291/**
292 * @interface
293 */
294remoting.ClientPluginFactory = function() {};
295
296/**
297 * @param {Element} container The container for the embed element.
298 * @param {function(string, string):boolean} onExtensionMessage The handler for
299 *     protocol extension messages. Returns true if a message is recognized;
300 *     false otherwise.
301 * @return {remoting.ClientPlugin} A new client plugin instance.
302 */
303remoting.ClientPluginFactory.prototype.createPlugin =
304    function(container, onExtensionMessage) {};
305
306/**
307 * Preload the plugin to make instantiation faster when the user tries
308 * to connect.
309 */
310remoting.ClientPluginFactory.prototype.preloadPlugin = function() {};
311
312/**
313 * @type {remoting.ClientPluginFactory}
314 */
315remoting.ClientPlugin.factory = null;
316