Loading

owl-mach-ipc-unstable-v1.

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <protocol name="owl_mach_ipc_unstable_v1">
  3.  
  4.     <copyright>
  5.         Copyright © 2019 Sergey Bugaev
  6.  
  7.         Permission is hereby granted, free of charge, to any person obtaining a
  8.         copy of this software and associated documentation files (the "Software"),
  9.         to deal in the Software without restriction, including without limitation
  10.         the rights to use, copy, modify, merge, publish, distribute, sublicense,
  11.         and/or sell copies of the Software, and to permit persons to whom the
  12.         Software is furnished to do so, subject to the following conditions:
  13.  
  14.         The above copyright notice and this permission notice (including the next
  15.         paragraph) shall be included in all copies or substantial portions of the
  16.         Software.
  17.  
  18.         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  19.         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  20.         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  21.         THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  22.         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  23.         FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  24.         DEALINGS IN THE SOFTWARE.
  25.     </copyright>
  26.  
  27.     <interface name="zowl_mach_ipc_v1" version="1">
  28.         <description summary="communicate over Mach IPC">
  29.             TODO description
  30.         </description>
  31.  
  32.         <event name="bootstrap_name">
  33.             <description summary="announce the bootstrap name">
  34.                 By sending this event, the compositor announces the bootstrap service name
  35.                 it uses. The client is then expected to look up the compositor's Mach port
  36.                 using a call such as bootstrap_look_up().
  37.             </description>
  38.             <arg name="name" type="string"/>
  39.         </event>
  40.  
  41.         <request name="create_port">
  42.             <description summary="announce the intent to create a Mach port">
  43.                 This request creates a Mach port usable for communication between the client
  44.                 and the server, as well as a zowl_mach_ipc_port_v1 object that wraps the port.
  45.             </description>
  46.             <arg name="id" type="new_id" interface="zowl_mach_ipc_port_v1"/>
  47.         </request>
  48.  
  49.         <request name="destroy" type="destructor">
  50.             <description summary="destroy zowl_mach_ipc_v1">
  51.                 Destroy this zowl_mach_ipc_v1 object and all the resources associated with
  52.                 it. Destroying a zowl_mach_ipc_v1 object while a Mach port that was created
  53.                 using it is in use is a protocol error.
  54.             </description>
  55.         </request>
  56.     </interface>
  57.  
  58.     <interface name="zowl_mach_ipc_port_v1" version="1">
  59.         <description summary="Mach port">
  60.             This interface represents a Mach IPC port. To make use of this port, it needs to
  61.             be assigned a role using some other protocol (such as owl-remote-layer).
  62.            
  63.             The client can retrieve the underlying mach_port_t (as a send right) using the
  64.             owl_mach_ipc_v1_retrieve_port() MIG routine, passing the secret sent by the server
  65.             in the zowl_mach_ipc_port_v1.secret event.
  66.         </description>
  67.  
  68.         <event name="secret">
  69.             <description summary="announce the secret key">
  70.                 This event announces the secret key that the client can pass into the
  71.                 owl_mach_ipc_v1_retrieve_port() MIG routine in order to retrieve the underlying
  72.                 mach_port_t of this zowl_mach_ipc_port_v1.
  73.                
  74.                 The secret key is both a security measure that prevents other processes from
  75.                 impersonating the client, and a way for the compositor to know which
  76.                 zowl_mach_ipc_port_v1 instance the port is requested for.
  77.             </description>
  78.             <arg name="secret" type="string"/>
  79.         </event>
  80.  
  81.         <request name="destroy" type="destructor">
  82.             <description summary="destroy zowl_mach_ipc_port_v1">
  83.                 Destroy this zowl_mach_ipc_port_v1 object and all the resources associated
  84.                 with it, including the underlying Mach port, if it is still valid.
  85.             </description>
  86.         </request>
  87.     </interface>
  88. </protocol>