Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add an <internet/> kind to requires/recommends/supports #421

Closed
wants to merge 2 commits into from
+362 −7
Closed

Add an <internet/> kind to requires/recommends/supports #421

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8641c14
spec: Add an <internet/> kind to requires/recommends/supports
pwithnall Jul 23, 2022
901a5cc
as-relation: Add support for the new <internet/> requires/recommends …
pwithnall Jul 23, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
52 docs/xml/metainfo-component.xml
View file
Open in desktop
@@ -1106,6 +1106,58 @@
</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 significantly degraded.</para></listitem>
<listitem><para><code>offline-only</code> - Never uses the internet, even if it’s available.</para></listitem>
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is the value in case an application can use the internet to enhance the experience, but otherwise does not need to and would also work perfectly fine offline? (e.g. a media player fetching cover art for songs from the web, but which would play them perfectly find just as well w/o internet connection)
Would that be maybe:

<supports>
  <internet>always</internet>
</supports>

<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>]]></programlisting>
<para>Valid for: <literal>requires</literal>, <literal>recommends</literal>, <literal>supports</literal></para>
</listitem>
</varlistentry>

</variablelist>
</listitem>

177 src/as-relation.c
View file
Open in desktop
@@ -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,16 @@ as_relation_load_from_xml (AsRelation *relation, AsContext *ctx, xmlNode *node,
g_autofree gchar *side_str = (gchar*) xmlGetProp (node, (xmlChar*) "side");
priv->display_side_kind = as_display_side_kind_from_string (side_str);

g_free (priv->version);
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know it's not your code, but what about g_free (g_steal_pointer (&priv->version)) or as_relation_set_version (relation, NULL)?

priv->version = NULL;
} else if (priv->item_kind == AS_RELATION_ITEM_KIND_INTERNET) {
g_autofree gchar *bandwidth_str = (gchar*) xmlGetProp (node, (xmlChar*) "bandwidth_mbitps");
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

g_autofree gchar *bandwidth_str = as_xml_get_prop_value (node, "bandwidth_mbitps");
(a bit nicer to read)


if (bandwidth_str != NULL)
priv->bandwidth_mbitps = g_ascii_strtoll (bandwidth_str, NULL, 10);
else
priv->bandwidth_mbitps = 0;

g_free (priv->version);
priv->version = NULL;
} else if (priv->item_kind != AS_RELATION_ITEM_KIND_CONTROL) {
@@ -1101,6 +1251,11 @@ as_relation_to_xml_node (AsRelation *relation, AsContext *ctx, xmlNode *root)
(xmlChar*) as_relation_item_kind_to_string (priv->item_kind),
(xmlChar*) as_control_kind_to_string (as_relation_get_value_control_kind (relation)));

} else if (priv->item_kind == AS_RELATION_ITEM_KIND_INTERNET) {
n = xmlNewTextChild (root, NULL,
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You could use as_xml_add_text_node here, but that's optional :-)

(xmlChar*) as_relation_item_kind_to_string (priv->item_kind),
(xmlChar*) as_internet_kind_to_string (as_relation_get_value_internet_kind (relation)));

} else {
n = xmlNewTextChild (root, NULL,
(xmlChar*) as_relation_item_kind_to_string (priv->item_kind),
@@ -1115,6 +1270,13 @@ as_relation_to_xml_node (AsRelation *relation, AsContext *ctx, xmlNode *root)
xmlNewProp (n, (xmlChar*) "compare",
(xmlChar*) 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) {
xmlNewProp (n,
@@ -1161,6 +1323,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) {
@@ -1204,6 +1368,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));
}
@@ -1268,6 +1436,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),
33 src/as-relation.h
View file
Open in desktop
@@ -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);