User input control information in AppStream

docs/sources/metainfo/component.xml

@@ -717,7 +717,7 @@
 			</para>
 
 			<variablelist>
-			<varlistentry>
+			<varlistentry id="tag-requires-recommends-id">
 				<term>&lt;id/&gt;</term>
 				<listitem>
 				<para>
@@ -729,7 +729,7 @@
 				</listitem>
 			</varlistentry>
 
-			<varlistentry>
+			<varlistentry id="tag-requires-recommends-modalias">
 				<term>&lt;modalias/&gt;</term>
 				<listitem>
 				<para>
@@ -742,7 +742,7 @@
 				</listitem>
 			</varlistentry>
 
-			<varlistentry>
+			<varlistentry id="tag-requires-recommends-kernel">
 				<term>&lt;kernel/&gt;</term>
 				<listitem>
 				<para>
@@ -755,7 +755,7 @@
 				</listitem>
 			</varlistentry>
 
-			<varlistentry>
+			<varlistentry id="tag-requires-recommends-memory">
 				<term>&lt;memory/&gt;</term>
 				<listitem>
 				<para>
@@ -771,7 +771,7 @@
 				</listitem>
 			</varlistentry>
 
-			<varlistentry>
+			<varlistentry id="tag-requires-recommends-firmware">
 				<term>&lt;firmware/&gt;</term>
 				<listitem>
 				<para>
@@ -789,6 +789,48 @@
 				</listitem>
 			</varlistentry>
 
+			<varlistentry id="tag-requires-recommends-control">
+				<term>&lt;control/&gt;</term>
+				<listitem>
+				<para>
+					This item type can be used to recommend or require certain ways a user can control the software. This usually maps to certain methods
+					of input. If multiples of these tag are found within a requires/recommends block, only one of them needs to be satisfied on the system
+					to mark an application as compatible. This means if <literal>touch</literal> and <literal>pointing</literal> are both recommended as controls,
+					an system that only has a mouse and no touchscreen will still be considered able to run the application.
+					Valid values for this tag are:
+				</para>
+				<itemizedlist>
+					<listitem><para><code>pointing</code> - Input via mouse/cursors/other pointing devices is possible</para></listitem>
+					<listitem><para><code>keyboard</code> - Keyboard input is possible</para></listitem>
+					<listitem><para><code>console</code> - Control via a console / command-line interface</para></listitem>
+					<listitem><para><code>touch</code> - Input by touching a surface with fingers is possible</para></listitem>
+					<listitem><para><code>gamepad</code> - The component supports gamepads (any game controller with wheels/buttons/joysticks)</para></listitem>
+					<listitem><para><code>voice</code> - The software can be controlled via voice recognition/activation</para></listitem>
+					<listitem><para><code>vision</code> - The software can be controlled by computer vision / visual object and sign detection</para></listitem>
+				</itemizedlist>
+				<para>
+					If a control type is <emphasis>recommended</emphasis>, it means the software supports the given method of user input. As long as one of the input methods
+					is available on the system, the software can be used. Installation on systems without the given control is still permitted.
+					If a control type is <emphasis>required</emphasis>, the same applies, but the software installed should refuse to install the application on devices which
+					do not have at least one of the input methods. It is therefore advised to only use the <code>control</code> tag in <code>recommends</code> listings,
+					and avoid to use it in <code>requires</code>.
+				</para>
+				<para>
+					For certain component types, some permitted controls are implicitly assumed: For <link linkend="sect-Metadata-Application">desktop-application</link>
+					and <link linkend="sect-Metadata-WebApplication">web-application</link> components, <literal>pointing</literal> and <literal>keyboard</literal> controls
+					are assumed.
+					For <link linkend="sect-Metadata-ConsoleApplication">console-application</link>, control via <literal>console</literal> is assumed.
+				</para>
+				<para>
+					Example control recommendation:
+				</para>
+				<programlisting language="XML"><![CDATA[<recommends>
+  <control>pointing</control>
+  <control>keyboard</control>
+  <control>touch</control>
+</recommends>]]></programlisting>
+				</listitem>
+			</varlistentry>
 
 			</variablelist>
 		</listitem>

src/as-relation.c

@@ -114,6 +114,8 @@ as_relation_item_kind_to_string (AsRelationItemKind kind)
 		return "memory";
 	if (kind == AS_RELATION_ITEM_KIND_FIRMWARE)
 		return "firmware";
+	if (kind == AS_RELATION_ITEM_KIND_CONTROL)
+		return "control";
 	return "unknown";
 }
 
@@ -140,6 +142,8 @@ as_relation_item_kind_from_string (const gchar *kind_str)
 		return AS_RELATION_ITEM_KIND_MEMORY;
 	if (g_strcmp0 (kind_str, "firmware") == 0)
 		return AS_RELATION_ITEM_KIND_FIRMWARE;
+	if (g_strcmp0 (kind_str, "control") == 0)
+		return AS_RELATION_ITEM_KIND_CONTROL;
 	return AS_RELATION_ITEM_KIND_UNKNOWN;
 }
 
@@ -251,6 +255,66 @@ as_relation_compare_to_symbols_string (AsRelationCompare compare)
 	return NULL;
 }
 
+/**
+ * as_control_kind_to_string:
+ * @kind: the #AsControlKind.
+ *
+ * Converts the enumerated value to a text representation.
+ *
+ * Returns: string version of @kind
+ *
+ * Since: 0.12.11
+ **/
+const gchar*
+as_control_kind_to_string (AsControlKind kind)
+{
+	if (kind == AS_CONTROL_KIND_POINTING)
+		return "pointing";
+	if (kind == AS_CONTROL_KIND_KEYBOARD)
+		return "keyboard";
+	if (kind == AS_CONTROL_KIND_CONSOLE)
+		return "console";
+	if (kind == AS_CONTROL_KIND_TOUCH)
+		return "touch";
+	if (kind == AS_CONTROL_KIND_GAMEPAD)
+		return "gamepad";
+	if (kind == AS_CONTROL_KIND_VOICE)
+		return "voice";
+	if (kind == AS_CONTROL_KIND_VISION)
+		return "vision";
+	return "unknown";
+}
+
+/**
+ * as_control_kind_from_string:
+ * @kind_str: the string.
+ *
+ * Converts the text representation to an enumerated value.
+ *
+ * Returns: a #AsControlKind or %AS_CONTROL_KIND_UNKNOWN for unknown
+ *
+ * Since: 0.12.11
+ **/
+AsControlKind
+as_control_kind_from_string (const gchar *kind_str)
+{
+	if (g_strcmp0 (kind_str, "pointing") == 0)
+		return AS_CONTROL_KIND_POINTING;
+	if (g_strcmp0 (kind_str, "keyboard") == 0)
+		return AS_CONTROL_KIND_KEYBOARD;
+	if (g_strcmp0 (kind_str, "console") == 0)
+		return AS_CONTROL_KIND_CONSOLE;
+	if (g_strcmp0 (kind_str, "touch") == 0)
+		return AS_CONTROL_KIND_TOUCH;
+	if (g_strcmp0 (kind_str, "gamepad") == 0)
+		return AS_CONTROL_KIND_GAMEPAD;
+	if (g_strcmp0 (kind_str, "voice") == 0)
+		return AS_CONTROL_KIND_VOICE;
+	if (g_strcmp0 (kind_str, "vision") == 0)
+		return AS_CONTROL_KIND_VISION;
+	return AS_CONTROL_KIND_UNKNOWN;
+}
+
 /**
  * as_relation_finalize:
  **/
@@ -437,7 +501,7 @@ as_relation_get_value (AsRelation *relation)
  * as_relation_get_value_int:
  * @relation: an #AsRelation instance.
  *
- * Returns: The value of the item this #AsRelation is about as integer.
+ * Returns: The value of this #AsRelation item as an integer. Returns 0 if the value was no integer.
  *
  * Since: 0.12.0
  **/
@@ -450,6 +514,27 @@ as_relation_get_value_int (AsRelation *relation)
 	return g_ascii_strtoll (priv->value, NULL, 10);
 }
 
+/**
+ * as_relation_get_value_control_kind:
+ * @relation: an #AsRelation instance.
+ *
+ * Get the value of this #AsRelation item as #AsControlKind if the
+ * type of this relation is %AS_RELATION_ITEM_KIND_CONTROL.
+ * Otherwise return %AS_CONTROL_KIND_UNKNOWN
+ *
+ * Returns: a #AsControlKind or %AS_CONTROL_KIND_UNKNOWN in case the item is not of the right kind.
+ *
+ * Since: 0.12.11
+ **/
+AsControlKind
+as_relation_get_value_control_kind (AsRelation *relation)
+{
+	AsRelationPrivate *priv = GET_PRIVATE (relation);
+	if (priv->item_kind != AS_RELATION_ITEM_KIND_CONTROL)
+		return AS_CONTROL_KIND_UNKNOWN;
+	return as_control_kind_from_string (priv->value);
+}
+
 /**
  * as_relation_set_value:
  * @relation: an #AsRelation instance.

src/as-relation.h

@@ -68,6 +68,7 @@ typedef enum  {
  * @AS_RELATION_ITEM_KIND_KERNEL:	An operating system kernel (like Linux)
  * @AS_RELATION_ITEM_KIND_MEMORY:	A system RAM requirement
  * @AS_RELATION_ITEM_KIND_FIRMWARE:	A device firmware requirement (used by fwupd)
+ * @AS_RELATION_ITEM_KIND_CONTROL:	An input method for users to control software
  *
  * Type of the item an #AsRelation is for.
  **/
@@ -78,6 +79,7 @@ typedef enum  {
 	AS_RELATION_ITEM_KIND_KERNEL,
 	AS_RELATION_ITEM_KIND_MEMORY,
 	AS_RELATION_ITEM_KIND_FIRMWARE,
+	AS_RELATION_ITEM_KIND_CONTROL,
 	/*< private >*/
 	AS_RELATION_ITEM_KIND_LAST
 } AsRelationItemKind;
@@ -106,6 +108,32 @@ typedef enum {
 	AS_RELATION_COMPARE_LAST
 } AsRelationCompare;
 
+/**
+ * AsControlKind:
+ * @AS_CONTROL_KIND_UNKNOWN:	Unknown kind
+ * @AS_CONTROL_KIND_POINTING:	Mouse/cursors/other pointing device
+ * @AS_CONTROL_KIND_KEYBOARD:	Keyboard input
+ * @AS_CONTROL_KIND_CONSOLE:	Console / command-line interface
+ * @AS_CONTROL_KIND_TOUCH:	Touch input
+ * @AS_CONTROL_KIND_GAMEPAD:	Gamepad input (any game controller with wheels/buttons/joysticks)
+ * @AS_CONTROL_KIND_VOICE:	Control via voice recognition/activation
+ * @AS_CONTROL_KIND_VISION:	Computer vision / visual object and sign detection
+ *
+ * Kind of an input method for users to control software
+ **/
+typedef enum {
+	AS_CONTROL_KIND_UNKNOWN,
+	AS_CONTROL_KIND_POINTING,
+	AS_CONTROL_KIND_KEYBOARD,
+	AS_CONTROL_KIND_CONSOLE,
+	AS_CONTROL_KIND_TOUCH,
+	AS_CONTROL_KIND_GAMEPAD,
+	AS_CONTROL_KIND_VOICE,
+	AS_CONTROL_KIND_VISION,
+	/*< private >*/
+	AS_CONTROL_KIND_LAST
+} AsControlKind;
+
 const gchar		*as_relation_kind_to_string (AsRelationKind kind);
 AsRelationKind		as_relation_kind_from_string (const gchar *kind_str);
 
@@ -116,6 +144,9 @@ AsRelationCompare	as_relation_compare_from_string (const gchar *compare_str);
 const gchar		*as_relation_compare_to_string (AsRelationCompare compare);
 const gchar		*as_relation_compare_to_symbols_string (AsRelationCompare compare);
 
+const gchar		*as_control_kind_to_string (AsControlKind kind);
+AsControlKind		as_control_kind_from_string (const gchar *kind_str);
+
 AsRelation		*as_relation_new (void);
 
 AsRelationKind		as_relation_get_kind (AsRelation *relation);
@@ -136,6 +167,7 @@ void			as_relation_set_version (AsRelation *relation,
 
 const gchar		*as_relation_get_value (AsRelation *relation);
 gint			as_relation_get_value_int (AsRelation *relation);
+AsControlKind		as_relation_get_value_control_kind (AsRelation *relation);
 void			as_relation_set_value (AsRelation *relation,
 					        const gchar *value);