Add an <internet/> kind to requires/recommends/supports /3

docs/xml/metainfo-component.xml

@@ -1106,6 +1106,71 @@
 				</listitem>
 			</varlistentry>
 
+			<varlistentry id="tag-relations-internet">
+				<term>&lt;internet/&gt;</term>
+				<listitem>
+				<para>
+					Require, recommend or support connectivity to the internet. The value of this item one of the following:
+				</para>
+				<itemizedlist>
+					<listitem>
+						<para>
+							<code>always</code> - Needs internet connectivity to work. If used in a <literal>recommends</literal> element,
+							then this indicates that the app can work without internet, but the experience will be degraded.
+						</para>
+					</listitem>
+					<listitem><para><code>offline-only</code> - Never uses the internet, even if it’s available.</para></listitem>
+					<listitem><para><code>first-run</code> - Uses the internet the first time the application is run, but not normally afterwards.</para></listitem>
+				</itemizedlist>
+				<para>
+					If the value of <literal>&lt;internet/&gt;</literal> is not <literal>offline-only</literal>, the <literal>bandwidth_mbitps</literal> attribute can be
+					set to a bandwidth (in Mbit/s) which is the minimum internet bandwidth needed for the application to be usable. If this attribute is not set, it’s
+					assumed that the application is usable with all internet connections.
+				</para>
+				<para>
+					Examples:
+				</para>
+				<programlisting language="XML"><![CDATA[<!-- always needs the internet -->
+<requires>
+  <internet>always</internet>
+</requires>
+
+<!-- always needs the internet and has a degraded experience if it’s not at least 2Mbit/s -->
+<requires>
+  <internet bandwidth_mbitps="2">always</internet>
+</requires>
+
+<!-- never uses the internet, even if available -->
+<requires>
+  <internet>never</internet>
+</requires>
+
+<!-- requires the internet on first run -->
+<requires>
+  <internet>first-run</internet>
+</requires>
+
+<!-- can work without the internet, but with a degraded experience -->
+<recommends>
+  <internet>always</internet>
+</recommends>
+
+<!-- recommends the internet for when it’s first run, but can work without -->
+<recommends>
+  <internet>first-run</internet>
+</recommends>
+
+<!-- requires the internet on first run, can run without it afterwards but with a degraded experience -->
+<requires>
+  <internet>first-run</internet>
+</requires>
+<recommends>
+  <internet>always</internet>
+</recommends>]]></programlisting>
+				<para>Valid for: <literal>requires</literal>, <literal>recommends</literal>, <literal>supports</literal></para>
+				</listitem>
+			</varlistentry>
+
 			</variablelist>
 		</listitem>
 

src/as-relation.c

@@ -50,6 +50,9 @@ typedef struct
 	/* specific to "display_length" relations */
 	AsDisplaySideKind display_side_kind;
 	AsDisplayLengthKind display_length_kind;
+
+	/* specific to "internet" relations */
+	guint bandwidth_mbitps;
 } AsRelationPrivate;
 
 G_DEFINE_TYPE_WITH_PRIVATE (AsRelation, as_relation, G_TYPE_OBJECT)
@@ -129,6 +132,8 @@ as_relation_item_kind_to_string (AsRelationItemKind kind)
 		return "display_length";
 	if (kind == AS_RELATION_ITEM_KIND_HARDWARE)
 		return "hardware";
+	if (kind == AS_RELATION_ITEM_KIND_INTERNET)
+		return "internet";
 	return "unknown";
 }
 
@@ -161,6 +166,8 @@ as_relation_item_kind_from_string (const gchar *kind_str)
 		return AS_RELATION_ITEM_KIND_DISPLAY_LENGTH;
 	if (g_strcmp0 (kind_str, "hardware") == 0)
 		return AS_RELATION_ITEM_KIND_HARDWARE;
+	if (g_strcmp0 (kind_str, "internet") == 0)
+		return AS_RELATION_ITEM_KIND_INTERNET;
 	return AS_RELATION_ITEM_KIND_UNKNOWN;
 }
 
@@ -488,6 +495,50 @@ as_display_length_kind_to_string (AsDisplayLengthKind kind)
 	return "unknown";
 }
 
+/**
+ * as_internet_kind_from_string:
+ * @kind_str: the string.
+ *
+ * Converts the text representation to an enumerated value.
+ *
+ * Returns: a #AsInternetKind or %AS_INTERNET_KIND_UNKNOWN for unknown
+ *
+ * Since: 0.15.5
+ **/
+AsInternetKind
+as_internet_kind_from_string (const gchar *kind_str)
+{
+	if (g_strcmp0 (kind_str, "always") == 0)
+		return AS_INTERNET_KIND_ALWAYS;
+	if (g_strcmp0 (kind_str, "offline-only") == 0)
+		return AS_INTERNET_KIND_OFFLINE_ONLY;
+	if (g_strcmp0 (kind_str, "first-run") == 0)
+		return AS_INTERNET_KIND_FIRST_RUN;
+	return AS_INTERNET_KIND_UNKNOWN;
+}
+
+/**
+ * as_internet_kind_to_string:
+ * @kind: the #AsInternetKind.
+ *
+ * Converts the enumerated value to a text representation.
+ *
+ * Returns: string version of @kind
+ *
+ * Since: 0.15.5
+ **/
+const gchar *
+as_internet_kind_to_string (AsInternetKind kind)
+{
+	if (kind == AS_INTERNET_KIND_ALWAYS)
+		return "always";
+	if (kind == AS_INTERNET_KIND_OFFLINE_ONLY)
+		return "offline-only";
+	if (kind == AS_INTERNET_KIND_FIRST_RUN)
+		return "first-run";
+	return "unknown";
+}
+
 /**
  * as_relation_finalize:
  **/
@@ -806,6 +857,93 @@ as_relation_set_value_control_kind (AsRelation *relation, AsControlKind kind)
 	as_relation_set_value_var (relation, g_variant_new_int32 (kind));
 }
 
+/**
+ * as_relation_get_value_internet_kind:
+ * @relation: an #AsRelation instance.
+ *
+ * Get the value of this #AsRelation item as #AsInternetKind if the
+ * type of this relation is %AS_RELATION_ITEM_KIND_INTERNET.
+ * Otherwise return %AS_INTERNET_KIND_UNKNOWN
+ *
+ * Returns: a #AsInternetKind or %AS_INTERNET_KIND_UNKNOWN in case the item is not of the right kind.
+ *
+ * Since: 0.15.5
+ **/
+AsInternetKind
+as_relation_get_value_internet_kind (AsRelation *relation)
+{
+	AsRelationPrivate *priv = GET_PRIVATE (relation);
+	if (priv->item_kind != AS_RELATION_ITEM_KIND_INTERNET)
+		return AS_INTERNET_KIND_UNKNOWN;
+	if (priv->value == NULL)
+		return AS_INTERNET_KIND_UNKNOWN;
+	return (AsInternetKind) g_variant_get_int32 (priv->value);
+}
+
+/**
+ * as_relation_set_value_internet_kind:
+ * @relation: an #AsRelation instance.
+ * @kind: an #AsInternetKind
+ *
+ * Set relation item value from an #AsInternetKind.
+ *
+ * Since: 0.15.5
+ **/
+void
+as_relation_set_value_internet_kind (AsRelation *relation, AsInternetKind kind)
+{
+	as_relation_set_value_var (relation, g_variant_new_int32 (kind));
+}
+
+/**
+ * as_relation_get_value_internet_bandwidth:
+ * @relation: an #AsRelation instance.
+ *
+ * If this #AsRelation is of kind %AS_RELATION_ITEM_KIND_INTERNET, return the
+ * minimum bandwidth requirement of the component, if set.
+ *
+ * If the relation is of a different kind, or the requirement isn’t set, this
+ * returns `0`.
+ *
+ * Returns: The minimum bandwidth requirement, in Mbit/s.
+ * Since: 0.15.5
+ */
+guint
+as_relation_get_value_internet_bandwidth (AsRelation *relation)
+{
+	AsRelationPrivate *priv = GET_PRIVATE (relation);
+
+	if (priv->item_kind != AS_RELATION_ITEM_KIND_INTERNET)
+		return 0;
+
+	return priv->bandwidth_mbitps;
+}
+
+/**
+ * as-relation_set_value_internet_bandwidth:
+ * @relation: an #AsRelation instance.
+ * @bandwidth_mbitps: Minimum bandwidth requirement, in Mbit/s, or `0` for no
+ *     requirement.
+ *
+ * Sets the minimum bandwidth requirement of the component.
+ *
+ * This requires the relation to be of item kind
+ * %AS_RELATION_ITEM_KIND_INTERNET.
+ *
+ * Since: 0.15.5
+ */
+void
+as_relation_set_value_internet_bandwidth (AsRelation *relation,
+                                          guint       bandwidth_mbitps)
+{
+	AsRelationPrivate *priv = GET_PRIVATE (relation);
+
+	if (priv->item_kind != AS_RELATION_ITEM_KIND_INTERNET)
+		return;
+
+	priv->bandwidth_mbitps = bandwidth_mbitps;
+}
+
 /**
  * as_relation_get_value_px:
  * @relation: an #AsRelation instance.
@@ -1036,6 +1174,8 @@ as_relation_load_from_xml (AsRelation *relation, AsContext *ctx, xmlNode *node,
 
 	} else if (priv->item_kind == AS_RELATION_ITEM_KIND_CONTROL) {
 		as_relation_set_value_var (relation, g_variant_new_int32 (as_control_kind_from_string (content)));
+	} else if (priv->item_kind == AS_RELATION_ITEM_KIND_INTERNET) {
+		as_relation_set_value_var (relation, g_variant_new_int32 (as_internet_kind_from_string (content)));
 	} else {
 		as_relation_set_value_str (relation, content);
 	}
@@ -1044,6 +1184,15 @@ as_relation_load_from_xml (AsRelation *relation, AsContext *ctx, xmlNode *node,
 		g_autofree gchar *side_str = as_xml_get_prop_value (node, "side");
 		priv->display_side_kind = as_display_side_kind_from_string (side_str);
 
+		g_free (g_steal_pointer (&priv->version));
+	} else if (priv->item_kind == AS_RELATION_ITEM_KIND_INTERNET) {
+		g_autofree gchar *bandwidth_str = as_xml_get_prop_value (node, "bandwidth_mbitps");
+
+		if (bandwidth_str != NULL)
+			priv->bandwidth_mbitps = g_ascii_strtoll (bandwidth_str, NULL, 10);
+		else
+			priv->bandwidth_mbitps = 0;
+
 		g_free (g_steal_pointer (&priv->version));
 	} else if (priv->item_kind != AS_RELATION_ITEM_KIND_CONTROL) {
 		g_free (priv->version);
@@ -1100,6 +1249,11 @@ as_relation_to_xml_node (AsRelation *relation, AsContext *ctx, xmlNode *root)
 					  as_relation_item_kind_to_string (priv->item_kind),
 					  as_control_kind_to_string (as_relation_get_value_control_kind (relation)));
 
+	} else if (priv->item_kind == AS_RELATION_ITEM_KIND_INTERNET) {
+		n = as_xml_add_text_node (root,
+					  as_relation_item_kind_to_string (priv->item_kind),
+					  as_internet_kind_to_string (as_relation_get_value_internet_kind (relation)));
+
 	} else {
 		n = as_xml_add_text_node (root,
 					  as_relation_item_kind_to_string (priv->item_kind),
@@ -1114,6 +1268,13 @@ as_relation_to_xml_node (AsRelation *relation, AsContext *ctx, xmlNode *root)
 			as_xml_add_text_prop (n, "compare",
 					      as_relation_compare_to_string (priv->compare));
 
+	} else if (priv->item_kind == AS_RELATION_ITEM_KIND_INTERNET) {
+		if (priv->bandwidth_mbitps > 0) {
+			g_autofree gchar *bandwidth_str = g_strdup_printf ("%u", priv->bandwidth_mbitps);
+			xmlNewProp (n, (xmlChar*) "bandwidth_mbitps",
+				    (xmlChar*) bandwidth_str);
+		}
+
 	} else if ((priv->item_kind == AS_RELATION_ITEM_KIND_CONTROL) || (priv->item_kind == AS_RELATION_ITEM_KIND_MEMORY)) {
 	} else if (priv->version != NULL) {
 		as_xml_add_text_prop (n,
@@ -1160,6 +1321,8 @@ as_relation_load_from_yaml (AsRelation *relation, AsContext *ctx, GNode *node, G
 			g_strstrip (priv->version);
 		} else if (g_strcmp0 (entry, "side") == 0) {
 			priv->display_side_kind = as_display_side_kind_from_string (as_yaml_node_get_value (n));
+		} else if (g_strcmp0 (entry, "bandwidth_mbitps") == 0) {
+			priv->bandwidth_mbitps = g_ascii_strtoll (as_yaml_node_get_value (n), NULL, 10);
 		} else {
 			AsRelationItemKind kind = as_relation_item_kind_from_string (entry);
 			if (kind == AS_RELATION_ITEM_KIND_UNKNOWN) {
@@ -1203,6 +1366,10 @@ as_relation_load_from_yaml (AsRelation *relation, AsContext *ctx, GNode *node, G
 				as_relation_set_value_var (relation,
 							   g_variant_new_int32 (as_control_kind_from_string (as_yaml_node_get_value (n))));
 
+			} else if (kind == AS_RELATION_ITEM_KIND_INTERNET) {
+				as_relation_set_value_var (relation,
+							   g_variant_new_int32 (as_internet_kind_from_string (as_yaml_node_get_value (n))));
+
 			} else {
 				as_relation_set_value_str (relation, as_yaml_node_get_value (n));
 			}
@@ -1267,6 +1434,15 @@ as_relation_emit_yaml (AsRelation *relation, AsContext *ctx, yaml_emitter_t *emi
 					   as_relation_item_kind_to_string (priv->item_kind),
 					   as_relation_get_value_int (relation));
 
+	} else if (priv->item_kind == AS_RELATION_ITEM_KIND_INTERNET) {
+		as_yaml_emit_entry (emitter,
+				    as_relation_item_kind_to_string (priv->item_kind),
+				    as_internet_kind_to_string (as_relation_get_value_internet_kind (relation)));
+		if (priv->bandwidth_mbitps > 0)
+			as_yaml_emit_entry_uint64 (emitter,
+						   "bandwidth_mbitps",
+						   priv->bandwidth_mbitps);
+
 	} else {
 		as_yaml_emit_entry (emitter,
 				    as_relation_item_kind_to_string (priv->item_kind),

src/as-relation.h

@@ -73,6 +73,7 @@ typedef enum  {
  * @AS_RELATION_ITEM_KIND_CONTROL:		An input method for users to control software
  * @AS_RELATION_ITEM_KIND_DISPLAY_LENGTH:	Display edge length
  * @AS_RELATION_ITEM_KIND_HARDWARE:		A Computer Hardware ID (CHID) to depend on system hardware
+ * @AS_RELATION_ITEM_KIND_INTERNET:		Internet connectivity (Since: 0.15.5)
  *
  * Type of the item an #AsRelation is for.
  **/
@@ -86,6 +87,7 @@ typedef enum  {
 	AS_RELATION_ITEM_KIND_CONTROL,
 	AS_RELATION_ITEM_KIND_DISPLAY_LENGTH,
 	AS_RELATION_ITEM_KIND_HARDWARE,
+	AS_RELATION_ITEM_KIND_INTERNET,
 	/*< private >*/
 	AS_RELATION_ITEM_KIND_LAST
 } AsRelationItemKind;
@@ -182,6 +184,27 @@ typedef enum  {
 	AS_DISPLAY_LENGTH_KIND_LAST
 } AsDisplayLengthKind;
 
+/**
+ * AsInternetKind:
+ * @AS_INTERNET_KIND_UNKNOWN:		Unknown
+ * @AS_INTERNET_KIND_ALWAYS:		Always requires/recommends internet
+ * @AS_INTERNET_KIND_OFFLINE_ONLY:	Application is offline-only
+ * @AS_INTERNET_KIND_FIRST_RUN:	Requires/Recommends internet on first run only
+ *
+ * Different internet connectivity requirements or recommendations for an
+ * application.
+ *
+ * Since: 0.15.5
+ **/
+typedef enum  {
+	AS_INTERNET_KIND_UNKNOWN,
+	AS_INTERNET_KIND_ALWAYS,
+	AS_INTERNET_KIND_OFFLINE_ONLY,
+	AS_INTERNET_KIND_FIRST_RUN,
+	/*< private >*/
+	AS_INTERNET_KIND_LAST
+} AsInternetKind;
+
 const gchar		*as_relation_kind_to_string (AsRelationKind kind);
 AsRelationKind		as_relation_kind_from_string (const gchar *kind_str);
 
@@ -201,6 +224,9 @@ AsDisplaySideKind	as_display_side_kind_from_string (const gchar *kind_str);
 const gchar		*as_display_length_kind_to_string (AsDisplayLengthKind kind);
 AsDisplayLengthKind	as_display_length_kind_from_string (const gchar *kind_str);
 
+const gchar		*as_internet_kind_to_string (AsInternetKind kind);
+AsInternetKind		as_internet_kind_from_string (const gchar *kind_str);
+
 AsRelation		*as_relation_new (void);
 
 AsRelationKind		as_relation_get_kind (AsRelation *relation);
@@ -242,6 +268,13 @@ AsDisplayLengthKind	as_relation_get_value_display_length_kind (AsRelation *relat
 void			as_relation_set_value_display_length_kind (AsRelation *relation,
 								   AsDisplayLengthKind kind);
 
+AsInternetKind		as_relation_get_value_internet_kind (AsRelation *relation);
+void			as_relation_set_value_internet_kind (AsRelation *relation,
+							     AsInternetKind kind);
+guint			as_relation_get_value_internet_bandwidth (AsRelation *relation);
+void			as_relation_set_value_internet_bandwidth (AsRelation *relation,
+								  guint bandwidth_mbitps);
+
 gboolean		as_relation_version_compare (AsRelation *relation,
 						     const gchar *version,
 						     GError **error);