1
/*********************************************************
2
* Copyright (C) 2008 VMware, Inc. All rights reserved.
4
* This program is free software; you can redistribute it and/or modify it
5
* under the terms of the GNU Lesser General Public License as published
6
* by the Free Software Foundation version 2.1 and no later version.
8
* This program is distributed in the hope that it will be useful, but
9
* WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
10
* or FITNESS FOR A PARTICULAR PURPOSE. See the Lesser GNU General Public
11
* License for more details.
13
* You should have received a copy of the GNU Lesser General Public License
14
* along with this program; if not, write to the Free Software Foundation, Inc.,
15
* 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
17
*********************************************************/
22
* Data shared between Tools, VMX, and UI for Unity
23
* RPCs, attributes, and variables.
27
* Breakdown of components involved in Unity:
29
* 1) Unity desktop target
31
* This is the system on which Unity windows will be displayed.
33
* Currently, the host operating system running VMware Workstation
36
* 2) Unity desktop source
38
* This is the system from which windows will be read and
39
* enumerated, and sent over to the Unity desktop target.
41
* An agent running on the desktop source will gather
42
* enumerated window data and send it to the Unity server.
44
* Currently, the virtualized guest operating system running
45
* under Workstation or Fusion, and VMware Tools running on that
48
* Source: bora-vmsoft/lib/unity
49
* bora/lib/unityWindowTracker
53
* This is a VNC-capable client that supports the extensions
54
* specified in VNCEncode_UnitySupported.
56
* Source: bora/apps/lib/cui/unityMgr.cc
57
* bora/apps/lib/cui/unityMgrVNC.cc
58
* bora/lib/vnc/vncDecode.c
60
* (used by the Workstation and Fusion hosted UI
65
* This is a VNC server that recognizes the Unity VNC extensions
66
* and handles instructing the agent running on the Unity desktop
67
* source to enumerate its windows and update the server with
68
* window metadata (geometry, title, shaped region, etc.)
70
* The Unity server gathers window metadata in its own Unity
71
* window tracker to decide what data to send to the Unity
74
* Source: bora/lib/unityWindowTracker
75
* bora/mks/hostops/vncBackend.c
76
* bora/lib/vnc/vncEncode.c
78
* (used by the VMX process)
83
* Overview of Unity enter operation
84
* ---------------------------------
86
* This is an idealized order of operations between the Unity
87
* client, server, and agent running on the Unity desktop source.
89
* Below the diagram are notes ([1], [2], [3]...) on the current
90
* implementation (VMware Workstation and Fusion).
92
* In the current implementation:
94
* "Client" is the hosted UI process
95
* "Server" is the vmware-vmx process
96
* "Agent" is the vmware-user process (VMware Tools per-user process)
98
* /--------\ /--------\ /-------\
99
* | Client | | Server | | Agent |
100
* \--------/ \--------/ \-------/
102
* [1] RPC to start Unity
103
* mode in desktop source
104
* =========================>
106
* [2] RPC to start enumerating
107
* windows of Unity desktop
108
* source (aka "Unity mode")
109
* =============================>
111
* [3] RPC response with full update
112
* containing window metadata
113
* of Unity desktop source
114
* <=============================
116
* [4] RPC response with
119
* <======================
121
* [5] Full update containing
122
* window metadata of Unity
124
* <======================
126
* [6] Repeating RPC updates with /->-\
127
* deltas for window metadata | |
128
* of Unity desktop source | |
129
* <============================= \-<-/
131
* [7] Delta update containing
132
* window metadata of Unity
134
* <======================
137
* -----------------------------------------------------------------------
139
* [1] Hosted UI opens VNC connection to VMX (through authd) with supported
140
* encodings of at least what VNCEncode_UnitySupported requires.
142
* MKS remote manager receives VNC connection socket connection
143
* and spins up MKS hostops VNC backend.
145
* [2] MKSRemoteMgr_StartUnityNotifications() asks Tools to start
146
* Unity by sending two TCLO RPCs via the backdoor (TODO: failure
147
* is currently ignored):
149
* 2a) UNITY_RPC_ENTER
150
* 2b) UNITY_RPC_GET_UPDATE_FULL
152
* [3] Tools receives UNITY_RPC_ENTER, spins up window update thread,
153
* and creates Unity window tracker. System settings and features not
154
* compatible with or conducive to Unity mode, such as screen savers
155
* and miscellaneous visual effects, are disabled for the duration of
156
* the Unity session. (See UnityPlatformSaveSystemSettings.)
158
* [4] Tools sends a UNITY_RPC_UNITY_ACTIVE (state change) RPC to the host
159
* indicating that it has successfully entered Unity mode. This is
160
* then recorded in VMDB under "vmx/guestTools/currentStatus/unityActive".
162
* [5] Tools receives UNITY_RPC_GET_UPDATE_FULL, and in response enumerates
163
* all windows running in the guest operating system. Windows suitable*
164
* for display in Unity mode are inserted into the Unity window tracker.
165
* Tools then returns the contents of the Unity window tracker as its
166
* response to the RPC.
168
* * Examples of suitable windows are application windows, tooltips,
169
* and menus. Examples of non-suitable windows are the desktop window,
170
* taskbar(s) (depending on configuration), and trays.
172
* [6] Tools continually reacts to changes in the guest operating system's
173
* windowing environment* and transforms them into input for the Unity
174
* window tracker. In response to certain events, Tools will flush the
175
* tracker's contents to the host via the RpcOut mechanism over the
176
* backdoor. Updates will be stored in a simple queue for step [7].
178
* * Example windowing events are window creation and deletion, move
181
* [7] The MKS remote manager periodically dequeues the guest's Unity window
182
* updates as part of its MKSRemoteMgr_FastPoll loop. The updates are then
183
* fed into the MKS's own Unity window tracker. The MKS Unity window
184
* tracker then coalesces window updates and transforms them into VNC
185
* rectangle updates for consumption by the UI.
188
#ifndef _UNITY_COMMON_H_
189
#define _UNITY_COMMON_H_
191
#define UNITY_MAX_SETTOP_WINDOW_COUNT 100
195
* Unity, GHI GuestRPC interface.
200
* @name Unity RPCs: Host-to-Guest
202
* @attention Any changes to this list @e must be reflected in the detailed
205
#define UNITY_RPC_ENTER "unity.enter"
206
#define UNITY_RPC_GET_UPDATE "unity.get.update"
207
#define UNITY_RPC_GET_WINDOW_PATH "unity.get.window.path"
208
#define UNITY_RPC_GET_BINARY_INFO "unity.get.binary.info"
209
#define UNITY_RPC_GET_BINARY_HANDLERS "unity.get.binary.handlers"
210
#define UNITY_RPC_OPEN_LAUNCHMENU "unity.launchmenu.open"
211
#define UNITY_RPC_GET_LAUNCHMENU_ITEM "unity.launchmenu.get.item"
212
#define UNITY_RPC_CLOSE_LAUNCHMENU "unity.launchmenu.close"
213
#define UNITY_RPC_WINDOW_SETTOP "unity.window.settop"
214
#define UNITY_RPC_WINDOW_CLOSE "unity.window.close"
215
#define UNITY_RPC_GET_WINDOW_CONTENTS "unity.get.window.contents"
216
#define UNITY_RPC_GET_ICON_DATA "unity.get.icon.data"
217
#define UNITY_RPC_EXIT "unity.exit"
218
#define UNITY_RPC_GET_UPDATE_FULL "unity.get.update.full"
219
#define UNITY_RPC_GET_UPDATE_INCREMENTAL "unity.get.update.incremental"
220
#define UNITY_RPC_SHELL_OPEN "unity.shell.open"
221
#define UNITY_RPC_SHOW_TASKBAR "unity.show.taskbar"
222
#define UNITY_RPC_WINDOW_MOVE_RESIZE "unity.window.move_resize"
223
#define UNITY_RPC_DESKTOP_WORK_AREA_SET "unity.desktop.work_area.set"
224
#define UNITY_RPC_WINDOW_SHOW "unity.window.show"
225
#define UNITY_RPC_WINDOW_HIDE "unity.window.hide"
226
#define UNITY_RPC_WINDOW_MINIMIZE "unity.window.minimize"
227
#define UNITY_RPC_WINDOW_UNMINIMIZE "unity.window.restore"
228
#define UNITY_RPC_WINDOW_MAXIMIZE "unity.window.maximize"
229
#define UNITY_RPC_WINDOW_UNMAXIMIZE "unity.window.unmaximize"
230
#define UNITY_RPC_DESKTOP_CONFIG_SET "unity.desktop.config.set"
231
#define UNITY_RPC_DESKTOP_ACTIVE_SET "unity.desktop.active.set"
232
#define UNITY_RPC_WINDOW_DESKTOP_SET "unity.window.desktop.set"
233
#define UNITY_RPC_SET_OPTIONS "unity.set.options"
234
#define UNITY_RPC_WINDOW_STICK "unity.window.stick"
235
#define UNITY_RPC_WINDOW_UNSTICK "unity.window.unstick"
236
#define UNITY_RPC_CONFIRM_OPERATION "unity.operation.confirm"
237
#define UNITY_RPC_WINDOW_CONTENTS_REQUEST "unity.window.contents.request"
238
#define UNITY_RPC_REGISTER_PBRPCSERVER "unity.register.pbrpcserver"
239
#define UNITY_RPC_SEND_MOUSE_WHEEL "unity.sendMouseWheel"
241
#define GHI_RPC_GUEST_SHELL_ACTION "ghi.guest.shell.action"
242
#define GHI_RPC_SET_GUEST_HANDLER "ghi.guest.handler.set"
243
#define GHI_RPC_RESTORE_DEFAULT_GUEST_HANDLER "ghi.guest.handler.restoreDefault"
244
#define GHI_RPC_OUTLOOK_SET_TEMP_FOLDER "ghi.guest.outlook.set.tempFolder"
245
#define GHI_RPC_OUTLOOK_RESTORE_TEMP_FOLDER "ghi.guest.outlook.restore.tempFolder"
246
#define GHI_RPC_TRAY_ICON_START_UPDATES "ghi.guest.trayIcon.startUpdates"
247
#define GHI_RPC_TRAY_ICON_STOP_UPDATES "ghi.guest.trayIcon.stopUpates"
248
#define GHI_RPC_TRAY_ICON_SEND_EVENT "ghi.guest.trayIcon.sendEvent"
249
#define GHI_RPC_SET_FOCUSED_WINDOW "ghi.guest.setFocusedWindow"
250
#define GHI_RPC_GET_EXEC_INFO_HASH "ghi.guest.getExecInfoHash"
251
#define GHI_RPC_AUTOLOGON_REQUIREMENTS "ghi.guest.autologon.requirements"
252
#define GHI_RPC_AUTOLOGON_SET "ghi.guest.autologon.set"
253
#define GHI_RPC_AUTOLOGON_QUERY "ghi.guest.autologon.query"
254
#define GHI_RPC_AUTOLOGON_CLEAR "ghi.guest.autologon.clear"
259
* @name Unity RPCs: Guest-to-Host
261
* @attention Any changes to this list @e must be reflected in the detailed
264
#define UNITY_RPC_PUSH_UPDATE_CMD "tools.unity.push.update"
265
#define UNITY_RPC_VMX_SHOW_TASKBAR "vmx.unity.show.taskbar"
266
#define UNITY_RPC_UNITY_CAP "tools.capability.unity"
267
#define UNITY_RPC_SHOW_TASKBAR_CAP "tools.capability.unity.taskbar"
268
#define UNITY_RPC_UNITY_ACTIVE "unity.active"
269
#define GHI_RPC_LAUNCHMENU_CHANGE "tools.ghi.launchmenu.change"
270
#define GHI_RPC_PROTOCOL_HANDLER_INFO "tools.ghi.protocolhandler.info"
271
#define GHI_RPC_TRAY_ICON_UPDATE "ghi.guest.trayIcon.update"
272
#define GHI_RPC_HOST_SHELL_ACTION "ghi.host.shell.action"
273
#define UNITY_RPC_REQUEST_OPERATION "unity.operation.request"
274
#define UNITY_RPC_ACK_OPERATION "unity.operation.ack"
275
#define UNITY_RPC_WINDOW_CONTENTS_START "unity.window.contents.start"
276
#define UNITY_RPC_WINDOW_CONTENTS_CHUNK "unity.window.contents.chunk"
277
#define UNITY_RPC_WINDOW_CONTENTS_END "unity.window.contents.end"
283
* @name Unity start menus
285
* @todo Someone with GHI clue needs to correctly document these.
287
* Currently we have four possible unity start menu roots.
289
* @li @ref UNITY_START_MENU_LAUNCH_FOLDER is for all guest start menu
290
* 'Programs' items plus favorite items from guest start menu folder.
292
* @li @ref UNITY_START_MENU_FIXED_FOLDER is for special items like 'My
293
* Computer', 'My Documents', 'Control Panel', etc.
295
* @li @ref UNITY_START_MENU_ALL_HANDLERS_FOLDER is for all the applications
296
* that are known by the guest to open files.
298
* @li @ref UNITY_START_MENU_RESOLVED_LAUNCH_FOLDER is the same contents as
299
* @ref UNITY_START_MENU_LAUNCH_FOLDER however each item that is a shortcut
300
* (link) is resolved into its destination path.
302
* @li @ref UNITY_START_MENU_RECENT_DOCUMENTS_FOLDER is the list of recently
303
* used documents for the guest.
305
#define UNITY_START_MENU_LAUNCH_FOLDER "VMGuestLaunchItems"
306
#define UNITY_START_MENU_FIXED_FOLDER "VMGuestFixedItems"
307
#define UNITY_START_MENU_ALL_HANDLERS_FOLDER "VMGuestAllHandlers"
308
#define UNITY_START_MENU_RESOLVED_LAUNCH_FOLDER "VMGuestResolvedItems"
309
#define UNITY_START_MENU_RECENT_DOCUMENTS_FOLDER "VMGuestRecentDocuments"
312
#define UNITY_START_MENU_FLAG_USE_PROGRAMS_FOLDER_AS_ROOT 1
319
* @brief Tray icon event identifiers. See ghiTrayIcon.x.
321
* @note These identifiers are shared between tools and the VMX. For
322
* compatibility reasons, new events must be added at the end of this
323
* list, and existing event numbers should not be reused if an event
327
#define GHI_TRAY_ICON_EVENT_INVALID 0
328
#define GHI_TRAY_ICON_EVENT_LBUTTONDBLCLK 1
329
#define GHI_TRAY_ICON_EVENT_RIGHT_CLICK 2
330
#define GHI_TRAY_ICON_EVENT_LEFT_CLICK 3
333
* @brief Opaque Unity window identifier.
335
* UnityWindowIds are chosen by (and only have meaning to) the guest.
337
typedef uint32 UnityWindowId;
340
* @brief Unity desktop identifier.
342
* Starting from @c 0, references a particular Unity desktop.
343
* @note A window with a @c UnityDesktopId of -1 once meant that the window was
344
* sticky. This convention is deprecated in favor of
345
* @ref UNITY_WINDOW_ATTR_STICKY.
347
typedef int32 UnityDesktopId;
351
* @name Unity window states
353
* @deprecated These are deprecated in favor of window attributes and window
354
* types, and are retained for compatibility purposes only.
356
#define UNITY_WINDOW_STATE_MINIMIZED (1 << 0)
357
#define UNITY_WINDOW_STATE_IN_FOCUS (1 << 1)
358
#define UNITY_WINDOW_STATE_TOPMOST (1 << 2)
363
* @brief Unity window attributes
365
* Unity window attributes are boolean flags that can be set in combination on a window.
366
* If they are not set by the guest, it is up to the host to decide on a reasonable
370
UNITY_WINDOW_ATTR_BORDERLESS = 0, ///< @deprecated
371
UNITY_WINDOW_ATTR_MINIMIZABLE = 1, ///< Can be minimized.
372
UNITY_WINDOW_ATTR_MAXIMIZABLE = 2, ///< Can be maximized.
373
UNITY_WINDOW_ATTR_MAXIMIZED = 3, /**< Is maximized. @note Not mutually exclusive
374
with @ref UNITY_WINDOW_STATE_MINIMIZED. */
375
UNITY_WINDOW_ATTR_CLOSABLE = 5, ///< Supports closing.
376
UNITY_WINDOW_ATTR_HAS_TITLEBAR = 6, ///< @deprecated
377
UNITY_WINDOW_ATTR_VISIBLE = 7, ///< @deprecated
378
UNITY_WINDOW_ATTR_CHILD_WINDOW = 8, ///< @deprecated
379
UNITY_WINDOW_ATTR_HAS_TASKBAR_BTN = 9, /**< Should appear in the taskbar.
380
@todo Consider deprecation? */
381
UNITY_WINDOW_ATTR_MOVABLE = 10, ///< Can be moved around the desktop.
382
UNITY_WINDOW_ATTR_RESIZABLE = 11, ///< Can be resized.
383
UNITY_WINDOW_ATTR_ALWAYS_ABOVE = 12, ///< Should stay on top of stack.
384
UNITY_WINDOW_ATTR_ALWAYS_BELOW = 13, ///< Should stay at bottom of stack.
385
UNITY_WINDOW_ATTR_DISABLED = 14, ///< Keyboard, mouse input is disabled.
386
UNITY_WINDOW_ATTR_NOACTIVATE = 15, /**< Does not raise to foreground via mouse
387
click, alt-tab, etc. */
388
UNITY_WINDOW_ATTR_SYSMENU = 16, /**< Window includes system menu (e.g., on
389
Windows, right-click the taskbar
391
UNITY_WINDOW_ATTR_TOOLWINDOW = 17,
392
UNITY_WINDOW_ATTR_APPWINDOW = 18, /**< Application window. Should appear in
393
task switchers, etc. */
394
UNITY_WINDOW_ATTR_FULLSCREENABLE = 19, ///< @deprecated
395
UNITY_WINDOW_ATTR_FULLSCREENED = 20, ///< @deprecated
396
UNITY_WINDOW_ATTR_ATTN_WANTED = 21, ///< Application wants user's attention.
397
UNITY_WINDOW_ATTR_SHADEABLE = 22, ///< @deprecated
398
UNITY_WINDOW_ATTR_SHADED = 23, ///< @deprecated
399
UNITY_WINDOW_ATTR_STICKABLE = 24, ///< Can be made sticky.
400
UNITY_WINDOW_ATTR_STICKY = 25, ///< Window should appear on all desktops.
401
UNITY_WINDOW_ATTR_MODAL = 26, /**< Modal window.
402
@todo But relative to which app? */
404
UNITY_MAX_ATTRIBUTES ///< Final, sentinel attribute entry.
405
} UnityWindowAttribute;
408
UNITY_WINDOW_TYPE_NONE = -1,
409
UNITY_WINDOW_TYPE_NORMAL = 0,
410
UNITY_WINDOW_TYPE_PANEL,
411
UNITY_WINDOW_TYPE_DIALOG,
412
UNITY_WINDOW_TYPE_MENU,
413
UNITY_WINDOW_TYPE_TOOLTIP,
414
UNITY_WINDOW_TYPE_SPLASH,
415
UNITY_WINDOW_TYPE_TOOLBAR,
416
UNITY_WINDOW_TYPE_DOCK,
417
UNITY_WINDOW_TYPE_DESKTOP,
418
UNITY_WINDOW_TYPE_COMBOBOX,
419
UNITY_WINDOW_TYPE_WIDGET,
421
UNITY_MAX_WINDOW_TYPES // Not a valid window type
425
UNITY_ICON_TYPE_MAIN = 0,
427
UNITY_MAX_ICONS // Not a valid icon type
430
typedef uint32 UnityIconSize; // Number of pixels on the larger side of the icon (which is usually square anyways).
431
#define UNITY_MAX_ICON_DATA_CHUNK ((1 << 16) - 100) // 64k, minus space for a few other return values
433
#define UNITY_DEFAULT_COLOR "#c0c0c0"
436
* List of operations that can be interlocked with the host, via a request, confirm,
437
* acknowledge sequence of RPCs.
445
* List of features (as a bitmask) which may be optionally enabled when entering
446
* Unity mode. By default all these features are disabled.
449
UNITY_ADD_HIDDEN_WINDOWS_TO_TRACKER = 1,
450
UNITY_INTERLOCK_MINIMIZE_OPERATION = 1 << 1,
451
UNITY_SEND_WINDOW_CONTENTS = 1 << 2,
452
UNITY_DISABLE_COMPOSITING_IN_GUEST = 1 << 3
457
* UNITY_RPC_REGISTER_PBRPCSERVER includes an enumerated Address Family to distinguish
458
* between PBRPC servers listening on TCP/IP sockets and those listening on VSockets.
461
InvalidAddressFamily = 0,
462
VSocketAddressFamily = 1,
463
INET4AddressFamily = 2
464
} UnityPBRPCAddressFamily;
468
* Multipage Doxygen documentation.
473
@defgroup UnityRpcHG Unity RPCs: Host-to-Guest
477
@brief Tell the guest to go into Unity mode.
481
@note On success, the guest will send @ref UNITY_RPC_UNITY_ACTIVE
482
with an argument of @c 1 to indicate it is in Unity mode.
485
@def UNITY_RPC_GET_UPDATE
486
@brief Get an incremental or full update of window changes detected by
488
@todo Deprecate this RPC in favor of using UNITY_RPC_GET_UPDATE_FULL
489
and UNITY_RPC_GET_UPDATE_INCREMENTAL
491
UNITY_RPC_GET_UPDATE ["incremental"]
493
@param incremental If present, do an incremental update, otherwise full.
494
@note A full update reports all current state of all windows,
495
while incremental sends updates received since the last
496
UNITY_RPC_GET_UPDATE was received.
497
@return See @ref UnityGetUpdateReturn.
500
@def UNITY_RPC_GET_WINDOW_PATH
501
@brief Return keys which uniquely identify a window and its owning
504
UNITY_RPC_GET_WINDOW_PATH UnityWindowId
506
@param UnityWindowId window to get path information from
509
retval ::= windowPath '\0' execPath '\0' '\0'
510
windowPath ::= ? UTF-8 string tying UnityWindowId to an executable ?
511
execPath ::= ? UTF-8 string uniquely identifying JUST the executable ?
513
@note Clients are to treat the returned paths @e only as unique
515
@sa UNITY_RPC_SHELL_OPEN
518
@def UNITY_RPC_GET_BINARY_INFO
519
@brief Return a list of icons for a window.
520
@todo Move this into a GHI-specific header.
521
@todo Give this RPC command an intuitive name.
523
UNITY_RPC_GET_BINARY_INFO windowPath
525
@param[in] windowPath UTF-8 encoded "window path" returned by
526
@ref UNITY_RPC_GET_WINDOW_PATH.
529
<retval> := <name><nul><count><nul><icon_data>{<icon_data>}
531
<name> := name of application
532
<count> := number of icons returned
533
<icon_data> := width<nul>height<nul>bgraSize<nul>bgraData<nul>
536
@note Icon data is in BGRA format. An alpha channel value of 255 means
537
"fully opaque", and a value of 0 means "fully transparent".
540
@def UNITY_RPC_GET_BINARY_HANDLERS
541
@brief Ask the guest to return filetypes (extensions) and URL protocols
542
supported by the guest.
543
@todo Move this into a GHI-specific header.
545
UNITY_RPC_GET_BINARY_HANDLERS
547
@sa ghiGetBinaryHandlers.x for format of data returned.
550
@def UNITY_RPC_OPEN_LAUNCHMENU
551
@brief Get the start menu sub-tree for a given item
552
@todo Move this into a GHI-specific header.
554
UNITY_RPC_OPEN_LAUNCHMENU root [flags]
556
@param[in] root Name of sub-tree, or "" for root of start menu.
557
@param[in] flags @ref UNITY_START_MENU_FLAG_USE_PROGRAMS_FOLDER_AS_ROOT
560
retval ::= count handle
562
count ::= ? Number of items in the sub-tree. ?
563
handle ::= ? Opaque 32-bit integer used with subsequent calls to UNITY_RPC_GET_LAUNCHMENU_ITEM. ?
567
@def UNITY_RPC_GET_LAUNCHMENU_ITEM
568
@brief Get the nth item in the menu sub-tree.
569
@todo Move this into a GHI-specific header.
571
UNITY_RPC_GET_LAUNCHMENU_ITEM handle index
573
@param[in] handle Handle returned by @ref UNITY_RPC_OPEN_LAUNCHMENU.
574
@param[in] index index of the item to retrieve (zero-indexed).
577
retval ::= name '\0' flags '\0' shellPath '\0' localName
579
name ::= ? Canonical item name used as a unique ID. ?
580
flags ::= 0 | 1 (* 0 = leaf node, 1 = directory *)
581
shellPath ::= ? Opaque executable path sent to UNITY_RPC_SHELL_OPEN. ?
582
localName ::= ? Localized item name displayed by UI. ?
584
@sa UNITY_RPC_SHELL_OPEN
587
@def UNITY_RPC_CLOSE_LAUNCHMENU
588
@brief Close the sub-menu, releasing all associated resources.
589
@todo Move this into a GHI-specific header.
591
UNITY_RPC_CLOSE_LAUNCHMENU handle
593
@param[in] handle Handle returned by @ref UNITY_RPC_OPEN_LAUNCHMENU.
596
@def UNITY_RPC_WINDOW_SETTOP
597
@brief Raise a group of windows to the top of the window stacking order.
599
UNITY_RPC_WINDOW_SETTOP UnityWindowId{ UnityWindowId}
601
@param[in] UnityWindowId{ UnityWindowId} group of windows to raise
602
@note Order of windows is bottom to top.
603
@note Only @ref UNITY_MAX_SETTOP_WINDOW_COUNT windows can be specified.
606
@def UNITY_RPC_WINDOW_CLOSE
607
@brief Close the specified window.
609
UNITY_RPC_WINDOW_CLOSE UnityWindowId
611
@param[in] UnityWindowId window to close
614
@def UNITY_RPC_GET_WINDOW_CONTENTS
615
@brief Retreive pixel contents of the Window.
617
UNITY_RPC_GET_WINDOW_CONTENTS UnityWindowId
619
@param[in] UnityWindowId UnityWindowId of window to get contents from
620
@return PNG image containing the window content.
623
@def UNITY_RPC_GET_ICON_DATA
624
@brief Return icon data for a specific window.
626
UNITY_RPC_GET_ICON_DATA UnityWindowId type size dataOffset dataLength
628
@param[in] UnityWindowId window to get icon data for
629
@param[in] type UNITY_ICON_TYPE_MAIN
630
@param[in] size size of icon e.g., 16, 32, 48
631
@param[in] dataOffset offset into icon data client desires
632
@param[in] dataLength number of bytes starting at dataOffset to return
633
@return PNG image containing the icon data.
637
@brief Cease enumerating windows and leave Unity mode.
641
@note On success, the guest will send a @ref UNITY_RPC_UNITY_ACTIVE
642
with an argument of 0 to indicate it has exited Unity mode.
645
@def UNITY_RPC_GET_UPDATE_FULL
646
@brief Equivalent to @ref UNITY_RPC_GET_UPDATE with no argument.
648
UNITY_RPC_GET_UPDATE_FULL
650
@return See @ref UnityGetUpdateReturn.
653
@def UNITY_RPC_GET_UPDATE_INCREMENTAL
654
@brief Equivalent to @ref UNITY_RPC_GET_UPDATE with an "incremental" argument.
656
UNITY_RPC_GET_UPDATE_INCREMENTAL
658
@return See @ref UnityGetUpdateReturn.
661
@def UNITY_RPC_SHELL_OPEN
662
@brief Open the application corresponding to the passed in URI or
664
@todo Move this into a GHI-specific header.
668
@param[in] path URI or path of executable to open
669
@note The URI is opaque to the caller, the caller supplies this URI
670
to the host with the expecation that it will be able to
671
understand the format when this RPC is invoked.
674
@def UNITY_RPC_SHOW_TASKBAR
675
@brief Show or hide the guest taskbar.
677
UNITY_RPC_SHOW_TASKBAR flag
679
@param[in] flag 0 to hide the taskbar, or 1 to show the taskbar.
682
@def UNITY_RPC_WINDOW_MOVE_RESIZE
683
@brief Change the geometry of the specified window.
685
UNITY_RPC_WINDOW_MOVE_RESIZE UnityWindowId x y width height
687
@param[in] UnityWindowId UnityWindowId of window to modify
688
@param[in] x x coordinate of desired window origin
689
@param[in] y y coordinate of desired window origin
690
@param[in] width desired width
691
@param[in] height desired height
692
@note Window origin refers to the upper left (north west) corner.
693
@note It is possible that the result will not be as requested due
694
to the layout policy of the guest desktop or window manager.
695
@return The new window location, dimensions.
697
retval ::= newX newY newWidth newHeight ;
698
newX ::= ? post-op north west corner X coordinate ? ;
699
newY ::= ? post-op north west corner Y coordinate ? ;
700
newWidth ::= ? post-op window width ? ;
701
newHeight ::= ? post-op window height ? ;
705
@def UNITY_RPC_DESKTOP_WORK_AREA_SET
706
@brief Specify the desktop work areas.
707
@todo Add more detail about this RPC and why it matters.
709
UNITY_RPC_DESKTOP_WORK_AREA_SET <work_areas>
711
@param[in] <work_areas> list of work areas
713
<work_areas> := <count>{ ',' x y width height }
714
<count> := number of work areas to follow, 0 or greater
718
@def UNITY_RPC_WINDOW_SHOW
719
@brief Make the specified window visible.
721
UNITY_RPC_WINDOW_SHOW UnityWindowId
723
@param[in] UnityWindowId UnityWindowId of window to show
726
@def UNITY_RPC_WINDOW_HIDE
727
@brief Hide the specified window.
729
UNITY_RPC_WINDOW_HIDE UnityWindowId
731
@param[in] UnityWindowId UnityWindowId of window to hide
734
@def UNITY_RPC_WINDOW_MINIMIZE
735
@brief Minimize the specified window.
737
UNITY_RPC_WINDOW_MINIMIZE UnityWindowId
739
@param[in] UnityWindowId UnityWindowId of window to minimize
742
@def UNITY_RPC_WINDOW_UNMINIMIZE
743
@brief Unminimizes a window to its pre-minimization state.
745
UNITY_RPC_WINDOW_UNMINIMIZE UnityWindowId
747
@param[in] UnityWindowId window to unminimize
748
@note This RPC originated as UNITY_RPC_WINDOW_RESTORE. The actual
749
GuestRpc command remains as "unity.window.restore" to maintain
750
backwards compatibility.
753
@def UNITY_RPC_WINDOW_MAXIMIZE
754
@brief Maximize the specified window.
756
UNITY_RPC_WINDOW_MAXIMIZE UnityWindowId
758
@param[in] UnityWindowId UnityWindowId of window to maximize
761
@def UNITY_RPC_WINDOW_UNMAXIMIZE
762
@brief Unmaximize the specified window.
764
UNITY_RPC_WINDOW_UNMAXIMIZE UnityWindowId
766
@param[in] UnityWindowId UnityWindowId of window to unmaximize
769
@def UNITY_RPC_DESKTOP_CONFIG_SET
770
@brief Send desktop (virtual workspaces) configuration.
772
UNITY_RPC_DESKTOP_CONFIG_SET configuration
774
@param[in] configuration <cell> {<cell>} <current>
776
<cell> := '{'row,col'}'
777
<current> := currently active cell
779
The RPC takes the form of a set of row, column pairs, each enclosed by
780
braces, and an integer. The number of rows and columns can be deduced
781
by looking for the max row and column value specified in these pairs.
782
The integer that follows the list of pairs defines the currently active
783
desktop, as an offset (starting at 0) of the pair list.\n\n
784
For example: <tt>{1,1} {1,2} {2,1} {2,2} 1</tt> specifies a 2 x 2 virtual
785
desktop where the upper right <tt>{1,2}</tt> is the currently active desktop.
788
@def UNITY_RPC_DESKTOP_ACTIVE_SET
789
@brief Change the active desktop to the value specified.
791
UNITY_RPC_DESKTOP_ACTIVE_SET offset
793
@param[in] offset Offset into desktop configuration, as defined by @ref UNITY_RPC_DESKTOP_CONFIG_SET, 0 or greater
796
@def UNITY_RPC_WINDOW_DESKTOP_SET
797
@brief Change the desktop of the specified window.
799
UNITY_RPC_WINDOW_DESKTOP_SET UnityWindowId offset
801
@param[in] UnityWindowId UnityWindowId of window to move
802
@param[in] offset Offset into desktop configuration, as defined by
803
@ref UNITY_RPC_DESKTOP_CONFIG_SET, 0 or greater.
805
@def UNITY_RPC_SET_OPTIONS
806
@brief Set optional behaviour for unity mode in the guest.
808
UNITY_RPC_SET_OPTIONS
810
@param[in] XDR encoded options mask.
811
@note This must be called before entering Unity mode - setting the options
812
after Unity mode has begun will result in undefined behaviour.
814
@def UNITY_RPC_WINDOW_STICK
815
@brief "Stick" a window to the screen.
817
UNITY_RPC_WINDOW_STICK UnityWindowId
819
@param[in] UnityWindowId UnityWindowId of window to stick.
821
@def UNITY_RPC_WINDOW_UNSTICK
822
@brief "Unstick" a window from the screen.
824
UNITY_RPC_WINDOW_UNSTICK UnityWindowId
826
@param[in] UnityWindowId UnityWindowId of window to unstick.
828
@def UNITY_RPC_CONFIRM_OPERATION
829
@brief Confirm (or deny) that a previously requested operation should now be performed.
831
UNITY_RPC_CONFIRM_OPERATION XDR_REP
833
@param[in] XDR_REP XDR Encoded (see unity.x) representation of arguments.
835
@def UNITY_RPC_SEND_MOUSE_WHEEL
836
@brief Send mouse wheel events to the window under the mouse.
838
UNITY_RPC_SEND_MOUSE_WHEEL horizontal deltaX deltaY deltaZ modifierFlags
840
@param[in] horizontal 0 to send vertical mouse wheel event, 1 for horizontal
841
@param[in] deltaX the horizontal distance the wheel is rotated
842
@param[in] deltaY the vertial distance the wheel is rotated
843
@param[in] deltaZ the distance the wheel is rotated in the Z axis
844
@param[in] modifierFlags modifier flags pressed during the event
846
@def UNITY_RPC_WINDOW_CONTENTS_REQUEST
847
@brief Request the asynchronous delivery of window contents.
849
UNITY_RPC_WINDOW_CONTENTS_REQUEST XDR_REP
851
@param[in] XDR_REP XDR Encoded (see unity.x) representation of arguments.
858
@defgroup UnityRpcGH Unity RPCs: Guest-to-Host
861
@def UNITY_RPC_PUSH_UPDATE_CMD
862
@brief Send a round of Unity Window Tracker updates to the host.
863
@todo doucment update format in unityWindowTracker.c
865
UNITY_RPC_PUSH_UPDATE_CMD commands
867
@param[in] A double-NUL-terminated string containing NUL-delimited update commands.
868
@note Updates are followed in the command string by Z-order information,
869
and active desktop information. The update format is documented in
870
@ref unityWindowTracker.c
873
@def UNITY_RPC_VMX_SHOW_TASKBAR
874
@brief Ask the host to send its "show taskbar" setting.
876
UNITY_RPC_VMX_SHOW_TASKBAR
880
@def UNITY_RPC_UNITY_CAP
881
@brief Tell the host if the guest is capable of supporting Unity or not.
883
UNITY_RPC_UNITY_CAP flag
885
@param[in] flag If 1, guest supports Unity. If 0, it does not
887
@def UNITY_RPC_SHOW_TASKBAR_CAP
888
@brief Tells the host if the guest is capable of showing and hiding the
891
UNITY_RPC_SHOW_TASKBAR_CAP flag
893
@param[in] flag If 1, taskbar visibility can be controlled. If 0, it cannot
895
@def GHI_RPC_LAUNCHMENU_CHANGE
896
@brief Inform the host that one or more launch menu items have changed.
897
@todo Move this define to a GHI-specific header.
899
GHI_RPC_LAUNCHMENU_CHANGE
903
@def GHI_RPC_PROTOCOL_HANDLER_INFO
904
@brief This command sends the list of protocol handlers to the host.
905
@todo Move this define to a GHI-specific header.
907
GHI_RPC_PROTOCOL_HANDLER_INFO
909
@param data XDR data containing protocol handler info.
910
@sa GHIPlatformGetProtocolHandlers for platform-specific list of handled protocols.
911
@sa ghiProtocolHandler.x for XDR data format.
914
@def UNITY_RPC_UNITY_ACTIVE
915
@brief Tell host we are entering or leaving Unity mode.
917
UNITY_RPC_UNITY_ACTIVE flag
919
@param[in] flag If 1, Unity is active. If 0, Unity is not active
921
@def UNITY_RPC_REQUEST_OPERATION
922
@brief Request that the host should allow the guest to perform an operation.
924
UNITY_RPC_REQUEST_OPERATION XDR_REP
926
@param[in] XDR_REP XDR Encoded (see unity.x) representation of arguments.
928
@def UNITY_RPC_ACK_OPERATION
929
@brief Acknowledge that a previously confirmed operations has been performed.
931
UNITY_RPC_ACK_OPERATION XDR_REP
933
@param[in] XDR_REP XDR Encoded (see unity.x) representation of arguments.
935
@def UNITY_RPC_WINDOW_CONTENTS_START
936
@brief The start of data for the pixel contents of the window.
938
UNITY_RPC_WINDOW_CONTENTS_START XDR_REP
940
@param[in] XDR_REP XDR Encoded (see unity.x) representation of arguments.
942
@def UNITY_RPC_WINDOW_CONTENTS_CHUNK
943
@brief One (<64KB) chunk of Pixel Data for a previously started window.
945
UNITY_RPC_WINDOW_CONTENTS_CHUNK XDR_REP
947
@param[in] XDR_REP XDR Encoded (see unity.x) representation of arguments.
949
@def UNITY_RPC_WINDOW_CONTENTS_END
950
@brief The end of data for the pixel contents of the window.
952
UNITY_RPC_WINDOW_CONTENTS_END XDR_REP
954
@param[in] XDR_REP XDR Encoded (see unity.x) representation of arguments.
961
* @page UnityGetUpdateReturn UNITY_RPC_GET_UPDATE RPC Return Value
963
* The return value of this RPC is a mapping of @ref UnityWindowTracker updates
964
* to GuestRpc-safe text strings. (Think of this simply as a poor-man's
965
* marshalling scheme between the UnityWindowTrackers running in the Unity
966
* Agent and Server (presently the VMware Tools and VMX/MKS, respectively).
969
* @li UNITY_RPC_GET_UPDATE
970
* @li UNITY_RPC_GET_UPDATE_FULL
971
* @li UNITY_RPC_GET_UPDATE_INCREMENTAL
973
* @section URGUReturnFormat Return value format
975
* The reply to the RPC is a double-null-terminated list of null-terminated
978
* Each string in the list has one of the following formats:
980
* @li <tt>"add" UnityWindowId arguments</tt> @par
981
* A window identified by @a UnityWindowId has just been created.
982
* The @a arguments are optional, and are not provided by all Tools.
983
* Arguments are space-separated key=value pairs, with the following
984
* keys: windowPath, execPath. The values are the same as what is
985
* returned by the @ref UNITY_RPC_GET_WINDOW_PATH RPC.
987
* @li <tt>"remove" UnityWindowId</tt> @par
988
* The window identified by @a UnityWindowId has been removed. Get rid
991
* @li <tt>"move" UnityWindowId x1 y1 x2 y2</tt> @par
992
* The window identified by @a UnityWindowId has moved or resized such
993
* that its top left corner rests at <tt>(x1, y1)</tt> and its bottom
994
* right at <tt>(x2, y2)</tt>.
996
* @li <tt>"region" UnityWindowId numrects</tt> @par
997
* The window identified by @a UnityWindowId has a not-rectangular window
998
* region (e.g. the curved corner windows in Windows XP). Immediately,
999
* after this message are @c numrects messages with the following (@ref
1002
* The actual window region is the union of all the rectangles in the list.
1003
* A value of 0 for @c numrects indicates that the window region should
1004
* be ignored (i.e. the window region is identical to the bounds of
1007
* @li <tt>"rect" x1 y1 x2 y2</tt> @par
1008
* @anchor rect Defines a rectangle in the coordinate system of the window
1009
* for this region (not the coordinate system of the desktop!!)
1011
* @li <tt>"title" UnityWindowId title</tt> @par
1012
* A window identified by @a UnityWindowId has just changed its to @a title.
1014
* @li <tt>"zorder" numWindows UnityWindowId {UnityWindowId}</tt> @par
1015
* Resets the Z order of @a numWindows Unity windows in top-to-bottom order.
1017
* @li <tt>"attr" UnityWindowId UnityWindowAttribute enabled</tt> @par
1018
* <tt>enabled ::= "0" | "1"</tt>\n The window identified by @a
1019
* UnityWindowId has an attribute enabled/disabled.
1021
* @li <tt>"type" UnityWindowId UnityWindowType</tt> @par
1022
* The window identified by @a UnityWindowId is of a certain type
1024
* @li <tt>"icon" UnityWindowId UnityIconType</tt> @par
1025
* The window identified by @a UnityWindowId has changed its icon type
1026
* to @a UnityIconType.
1028
* @li <tt>"desktop" UnityWindowId UnityDesktopId</tt> @par
1029
* The window identified by @a UnityWindowId has been moved to the desktop
1030
* identified by @a UnityDesktopId.
1032
* @li <tt>"activedesktop" UnityDesktopId</tt> @par
1033
* The desktop identified by @a UnityDesktopId has become active.
1036
* @sa UnityWindowId, UnityDesktopId, UnityWindowType, UnityIconType
added
removed
lib/include/unityCommon.h
