From 875e3c325d133c6cc67e980b8eb080faefb3d35d Mon Sep 17 00:00:00 2001
From: Isaac Freund <ifreund@ifreund.xyz>
Date: Thu, 14 Jan 2021 17:59:22 +0100
Subject: [PATCH] river-options: create protocol

---
 protocol/river-options-unstable-v1.xml | 147 +++++++++++++++++++++++++
 1 file changed, 147 insertions(+)
 create mode 100644 protocol/river-options-unstable-v1.xml

diff --git a/protocol/river-options-unstable-v1.xml b/protocol/river-options-unstable-v1.xml
new file mode 100644
index 0000000..87274e9
--- /dev/null
+++ b/protocol/river-options-unstable-v1.xml
@@ -0,0 +1,147 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="river_options_unstable_v1">
+  <copyright>
+    Copyright 2020 The River Developers
+
+    Permission to use, copy, modify, and/or distribute this software for any
+    purpose with or without fee is hereby granted, provided that the above
+    copyright notice and this permission notice appear in all copies.
+
+    THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+    WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+    MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+    ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+    WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+    ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+    OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+  </copyright>
+
+  <interface name="zriver_options_manager_v1" version="1">
+    <description summary="set and retrieve options">
+      This protocol allows clients to access a typed key-value store of
+      options. These options are identified by string keys and are scoped
+      either globally or per-output. This protocol does not define any
+      semantic meaning of the options, that is left up to compositors.
+
+      Compositors are free to set options themselves at any time, though
+      the type of any given option is immutable once set.
+
+      Options may never be unset once set.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the zriver_options_manager_v1 object">
+        This request indicates that the client will not use the manager object
+        any more. Objects that have been created through this instance are
+        not affected.
+      </description>
+    </request>
+
+    <request name="get_option_handle">
+      <description summary="get an option handle for the given key">
+        If the output argument is non-null, the option is local to the given
+        output. Otherwise it is considered global.
+      </description>
+      <arg name="key" type="string"/>
+      <arg name="output" type="object" interface="wl_output" allow-null="true"/>
+      <arg name="handle" type="new_id" interface="zriver_option_handle_v1"/>
+    </request>
+  </interface>
+
+  <interface name="zriver_option_handle_v1" version="1">
+    <description summary="handle to an option">
+      On binding this object, one of the events will immediately be sent by
+      the server to inform the client of the current state of the option. New
+      events will be sent as the state changes.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the handle">
+        This request indicates that the client will not use the
+        zriver_option_handle_v1 any more and that it may be safely destroyed.
+      </description>
+    </request>
+
+    <event name="unset">
+      <description summary="the option is currently unset">
+        The option with this key has never been set, so the first set_*_value
+        request received from any client will determine its type.
+
+        This can only ever be sent as the first event after binding this
+        interface as options cannot be unset once set.
+      </description>
+    </event>
+
+    <event name="int_value">
+      <description summary="the current value of the int option">
+        This indicates to the client that the option is of type int as well
+        as the current value of the option. Once set the type of the option
+        can never change.
+      </description>
+      <arg name="value" type="int"/>
+    </event>
+
+    <event name="uint_value">
+      <description summary="the current value of the uint option">
+        This indicates to the client that the option is of type uint as well
+        as the current value of the option. Once set the type of the option
+        can never change.
+      </description>
+      <arg name="value" type="uint"/>
+    </event>
+
+    <event name="fixed_value">
+      <description summary="the current value of the fixed option">
+        This indicates to the client that the option is of type fixed as
+        well as the current value of the option. Once set the type of the option
+        can never change.
+      </description>
+      <arg name="value" type="fixed"/>
+    </event>
+
+    <event name="string_value">
+      <description summary="the current value of the string option">
+        This indicates to the client that the option is of type string as
+        well as the current value of the option. Once set the type of the option
+        can never change.
+      </description>
+      <arg name="value" type="string" allow-null="true"/>
+    </event>
+
+    <request name="set_int_value">
+      <description summary="set the value of the option">
+        If the option is either unset or set to a value of type int,
+        this request sets the value of the option as well as the type if
+        previously unset. Otherwise the request is ignored.
+      </description>
+      <arg name="value" type="int"/>
+    </request>
+
+    <request name="set_uint_value">
+      <description summary="set the value of the option">
+        If the option is either unset or set to a value of type uint,
+        this request sets the value of the option as well as the type if
+        previously unset. Otherwise the request is ignored.
+      </description>
+      <arg name="value" type="uint"/>
+    </request>
+
+    <request name="set_fixed_value">
+      <description summary="set the value of the option">
+        If the option is either unset or set to a value of type fixed,
+        this request sets the value of the option as well as the type if
+        previously unset. Otherwise the request is ignored.
+      </description>
+      <arg name="value" type="fixed"/>
+    </request>
+
+    <request name="set_string_value">
+      <description summary="set the value of the option">
+        If the option is either unset or set to a value of type string,
+        this request sets the value of the option as well as the type if
+        previously unset. Otherwise the request is ignored.
+      </description>
+      <arg name="value" type="string" allow-null="true"/>
+    </request>
+  </interface>
+</protocol>