blob: 708b885f1b3a4d36c9983295f5257fb73090b4cb [file] [log] [blame]
/* GStreamer media licenses utility functions
* Copyright (C) 2011 Tim-Philipp Müller <tim centricular net>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Library General Public License for more details.
*
* You should have received a copy of the GNU Library General Public
* License along with this library; if not, write to the
* Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
* Boston, MA 02110-1301, USA.
*/
/**
* SECTION:gsttaglicenses
* @title: Licenses
* @short_description: utility functions for Creative Commons licenses
* @see_also: #GstTagList
*
* Provides information about Creative Commons media licenses, which are
* often expressed in media files as a license URI in tags. Also useful
* for applications creating media files, in case the user wants to license
* the content under a Creative Commons license.
*/
/* FIXME: add API to check obsolete-ness / replace-by */
#ifdef HAVE_CONFIG_H
#include "config.h"
#endif
#include <gst/gst.h>
#include <string.h>
#include <stdlib.h>
#include "tag.h"
#include "licenses-tables.dat"
#ifndef GST_DISABLE_GST_DEBUG
#define GST_CAT_DEFAULT ensure_debug_category()
static GstDebugCategory *
ensure_debug_category (void)
{
static gsize cat_gonce = 0;
if (g_once_init_enter (&cat_gonce)) {
gsize cat_done;
cat_done = (gsize) _gst_debug_category_new ("tag-licenses", 0,
"GstTag licenses");
g_once_init_leave (&cat_gonce, cat_done);
}
return (GstDebugCategory *) cat_gonce;
}
#else
#define ensure_debug_category() /* NOOP */
#endif /* GST_DISABLE_GST_DEBUG */
/* -------------------------------------------------------------------------
* Translations
* ------------------------------------------------------------------------- */
#ifdef ENABLE_NLS
static GVariant *
gst_tag_get_license_translations_dictionary (void)
{
static gsize var_gonce = 0;
if (g_once_init_enter (&var_gonce)) {
const gchar *dict_path;
GVariant *var = NULL;
GError *err = NULL;
gchar *data;
gsize len;
/* for gst-uninstalled */
dict_path = g_getenv ("GST_TAG_LICENSE_TRANSLATIONS_DICT");
if (dict_path == NULL)
dict_path = LICENSE_TRANSLATIONS_PATH;
GST_INFO ("Loading license translations from '%s'", dict_path);
if (g_file_get_contents (dict_path, &data, &len, &err)) {
var = g_variant_new_from_data (G_VARIANT_TYPE ("a{sa{ss}}"), data, len,
TRUE, (GDestroyNotify) g_free, data);
} else {
GST_WARNING ("Could not load translation dictionary %s", err->message);
g_error_free (err);
var = g_variant_new_array (G_VARIANT_TYPE ("{sa{ss}}"), NULL, 0);
}
g_once_init_leave (&var_gonce, (gsize) var);
}
return (GVariant *) var_gonce;
}
#endif
#ifdef ENABLE_NLS
static gboolean
gst_variant_lookup_string_value (GVariant * dict, const gchar * lang,
const gchar ** translation)
{
GVariant *trans;
trans = g_variant_lookup_value (dict, lang, G_VARIANT_TYPE ("s"));
if (trans == NULL)
return FALSE;
*translation = g_variant_get_string (trans, NULL);
/* string will stay valid */
g_variant_unref (trans);
GST_TRACE ("Result: '%s' for language '%s'", *translation, lang);
return TRUE;
}
#endif
static const gchar *
gst_license_str_translate (const gchar * s)
{
#ifdef ENABLE_NLS
GVariant *v, *dict, *trans;
v = gst_tag_get_license_translations_dictionary ();
g_assert (v != NULL);
dict = g_variant_lookup_value (v, s, G_VARIANT_TYPE ("a{ss}"));
if (dict != NULL) {
const gchar *const *lang;
const gchar *env_lang;
/* for unit tests */
if ((env_lang = g_getenv ("GST_TAG_LICENSE_TRANSLATIONS_LANG"))) {
if (gst_variant_lookup_string_value (dict, env_lang, &s))
GST_TRACE ("Result: '%s' for forced language '%s'", s, env_lang);
goto beach;
}
lang = g_get_language_names ();
while (lang != NULL && *lang != NULL) {
GST_TRACE ("Looking up '%s' for language '%s'", s, *lang);
trans = g_variant_lookup_value (dict, *lang, G_VARIANT_TYPE ("s"));
if (trans != NULL) {
s = g_variant_get_string (trans, NULL);
/* s will stay valid */
g_variant_unref (trans);
GST_TRACE ("Result: '%s'", s);
break;
}
GST_TRACE ("No result for '%s' for language '%s'", s, *lang);
++lang;
}
beach:
g_variant_unref (dict);
} else {
GST_WARNING ("No dict for string '%s'", s);
}
#endif
return s;
}
/* -------------------------------------------------------------------------
* License handling
* ------------------------------------------------------------------------- */
#define CC_LICENSE_REF_PREFIX "http://creativecommons.org/licenses/"
/* is this license 'generic' (and a base for any of the supported
* jurisdictions), or jurisdiction-specific only? */
#define JURISDICTION_GENERIC (G_GUINT64_CONSTANT (1) << 63)
static const gchar jurisdictions[] =
"ar\000at\000au\000be\000bg\000br\000ca\000ch\000cl\000cn\000co\000de\000"
"dk\000es\000fi\000fr\000hr\000hu\000il\000in\000it\000jp\000kr\000mk\000"
"mt\000mx\000my\000nl\000pe\000pl\000pt\000scotland\000se\000si\000tw\000"
"uk\000us\000za";
/**
* gst_tag_get_licenses:
*
* Returns a list of known license references (in form of URIs). This is
* useful for UIs to build a list of available licenses for tagging purposes
* (e.g. to tag an audio track appropriately in a video or audio editor, or
* an image in a camera application).
*
* Returns: (transfer full): NULL-terminated array of license strings. Free
* with g_strfreev() when no longer needed.
*/
gchar **
gst_tag_get_licenses (void)
{
GPtrArray *arr;
int i;
arr = g_ptr_array_new ();
for (i = 0; i < G_N_ELEMENTS (licenses); ++i) {
const gchar *jurs;
gboolean is_generic;
guint64 jbits;
gchar *ref;
jbits = licenses[i].jurisdictions;
is_generic = (jbits & JURISDICTION_GENERIC) != 0;
if (is_generic) {
ref = g_strconcat (CC_LICENSE_REF_PREFIX, licenses[i].ref, NULL);
GST_LOG ("Adding %2d %s (generic)", i, ref);
g_ptr_array_add (arr, ref);
jbits &= ~JURISDICTION_GENERIC;
}
jurs = jurisdictions;
while (jbits != 0) {
if ((jbits & 1)) {
ref = g_strconcat (CC_LICENSE_REF_PREFIX, licenses[i].ref, jurs, "/",
NULL);
GST_LOG ("Adding %2d %s (%s: %s)", i, ref,
(is_generic) ? "derived" : "specific", jurs);
g_ptr_array_add (arr, ref);
}
g_assert (jurs < (jurisdictions + sizeof (jurisdictions)));
jurs += strlen (jurs) + 1;
jbits >>= 1;
}
}
g_ptr_array_add (arr, NULL);
return (gchar **) g_ptr_array_free (arr, FALSE);
}
static gint
gst_tag_get_license_idx (const gchar * license_ref, const gchar ** jurisdiction)
{
const gchar *ref, *jur_suffix;
int i;
GST_TRACE ("Looking up '%s'", license_ref);
if (!g_str_has_prefix (license_ref, CC_LICENSE_REF_PREFIX)) {
GST_WARNING ("unknown license prefix in ref '%s'", license_ref);
return -1;
}
if (jurisdiction != NULL)
*jurisdiction = NULL;
ref = license_ref + sizeof (CC_LICENSE_REF_PREFIX) - 1;
for (i = 0; i < G_N_ELEMENTS (licenses); ++i) {
guint64 jbits = licenses[i].jurisdictions;
const gchar *jurs, *lref = licenses[i].ref;
gsize lref_len = strlen (lref);
/* table should have "foo/bar/" with trailing slash */
g_assert (lref[lref_len - 1] == '/');
if ((jbits & JURISDICTION_GENERIC)) {
GST_TRACE ("[%2d] %s checking generic match", i, licenses[i].ref);
/* exact match? */
if (strcmp (ref, lref) == 0)
return i;
/* exact match but without the trailing slash in ref? */
if (strncmp (ref, lref, lref_len - 1) == 0 && ref[lref_len - 1] == '\0')
return i;
}
if (!g_str_has_prefix (ref, lref))
continue;
GST_TRACE ("[%2d] %s checking jurisdictions", i, licenses[i].ref);
jbits &= ~JURISDICTION_GENERIC;
jur_suffix = ref + lref_len;
if (*jur_suffix == '\0')
continue;
jurs = jurisdictions;
while (jbits != 0) {
guint jur_len = strlen (jurs);
if ((jbits & 1)) {
if (strncmp (jur_suffix, jurs, jur_len) == 0 &&
(jur_suffix[jur_len] == '\0' || jur_suffix[jur_len] == '/')) {
GST_LOG ("matched %s to %s with jurisdiction %s (idx %d)",
license_ref, licenses[i].ref, jurs, i);
if (jurisdiction != NULL)
*jurisdiction = jurs;
return i;
}
}
g_assert (jurs < (jurisdictions + sizeof (jurisdictions)));
jurs += jur_len + 1;
jbits >>= 1;
}
}
GST_WARNING ("unhandled license ref '%s'", license_ref);
return -1;
}
/**
* gst_tag_get_license_flags:
* @license_ref: a license reference string in form of a URI,
* e.g. "http://creativecommons.org/licenses/by-nc-nd/2.0/"
*
* Get the flags of a license, which describe most of the features of
* a license in their most general form.
*
* Returns: the flags of the license, or 0 if the license is unknown
*/
GstTagLicenseFlags
gst_tag_get_license_flags (const gchar * license_ref)
{
int idx;
g_return_val_if_fail (license_ref != NULL, 0);
idx = gst_tag_get_license_idx (license_ref, NULL);
return (idx < 0) ? 0 : licenses[idx].flags;
}
/**
* gst_tag_get_license_nick:
* @license_ref: a license reference string in form of a URI,
* e.g. "http://creativecommons.org/licenses/by-nc-nd/2.0/"
*
* Get the nick name of a license, which is a short (untranslated) string
* such as e.g. "CC BY-NC-ND 2.0 UK".
*
* Returns: the nick name of the license, or NULL if the license is unknown
*/
const gchar *
gst_tag_get_license_nick (const gchar * license_ref)
{
GstTagLicenseFlags flags;
const gchar *creator_prefix, *res;
gchar *nick, *c;
g_return_val_if_fail (license_ref != NULL, NULL);
flags = gst_tag_get_license_flags (license_ref);
if ((flags & GST_TAG_LICENSE_CREATIVE_COMMONS_LICENSE)) {
creator_prefix = "CC ";
} else if ((flags & GST_TAG_LICENSE_FREE_SOFTWARE_FOUNDATION_LICENSE)) {
creator_prefix = "FSF ";
} else if (g_str_has_suffix (license_ref, "publicdomain/")) {
creator_prefix = "";
} else {
return NULL;
}
nick = g_strdup_printf ("%s%s", creator_prefix,
license_ref + sizeof (CC_LICENSE_REF_PREFIX) - 1);
g_strdelimit (nick, "/", ' ');
g_strchomp (nick);
for (c = nick; *c != '\0'; ++c)
*c = g_ascii_toupper (*c);
GST_LOG ("%s => nick %s", license_ref, nick);
res = g_intern_string (nick); /* for convenience */
g_free (nick);
return res;
}
/**
* gst_tag_get_license_title:
* @license_ref: a license reference string in form of a URI,
* e.g. "http://creativecommons.org/licenses/by-nc-nd/2.0/"
*
* Get the title of a license, which is a short translated description
* of the license's features (generally not very pretty though).
*
* Returns: the title of the license, or NULL if the license is unknown or
* no title is available.
*/
const gchar *
gst_tag_get_license_title (const gchar * license_ref)
{
int idx;
g_return_val_if_fail (license_ref != NULL, NULL);
idx = gst_tag_get_license_idx (license_ref, NULL);
if (idx < 0 || licenses[idx].title_idx < 0)
return NULL;
return gst_license_str_translate (&license_strings[licenses[idx].title_idx]);
}
/**
* gst_tag_get_license_description:
* @license_ref: a license reference string in form of a URI,
* e.g. "http://creativecommons.org/licenses/by-nc-nd/2.0/"
*
* Get the description of a license, which is a translated description
* of the license's main features.
*
* Returns: the description of the license, or NULL if the license is unknown
* or a description is not available.
*/
const gchar *
gst_tag_get_license_description (const gchar * license_ref)
{
int idx;
g_return_val_if_fail (license_ref != NULL, NULL);
idx = gst_tag_get_license_idx (license_ref, NULL);
if (idx < 0 || licenses[idx].desc_idx < 0)
return NULL;
return gst_license_str_translate (&license_strings[licenses[idx].desc_idx]);
}
/**
* gst_tag_get_license_jurisdiction:
* @license_ref: a license reference string in form of a URI,
* e.g. "http://creativecommons.org/licenses/by-nc-nd/2.0/"
*
* Get the jurisdiction code of a license. This is usually a two-letter
* ISO 3166-1 alpha-2 code, but there is also the special case of Scotland,
* for which no code exists and which is thus represented as "scotland".
*
* Known jurisdictions: ar, at, au, be, bg, br, ca, ch, cl, cn, co, de,
* dk, es, fi, fr, hr, hu, il, in, it, jp, kr, mk, mt, mx, my, nl, pe, pl,
* pt, scotland, se, si, tw, uk, us, za.
*
* Returns: the jurisdiction code of the license, or NULL if the license is
* unknown or is not specific to a particular jurisdiction.
*/
const gchar *
gst_tag_get_license_jurisdiction (const gchar * license_ref)
{
const gchar *jurisdiction;
int idx;
g_return_val_if_fail (license_ref != NULL, NULL);
idx = gst_tag_get_license_idx (license_ref, &jurisdiction);
return (idx < 0) ? NULL : jurisdiction;
}
/**
* gst_tag_get_license_version:
* @license_ref: a license reference string in form of a URI,
* e.g. "http://creativecommons.org/licenses/by-nc-nd/2.0/"
*
* Get the version of a license.
*
* Returns: the version of the license, or NULL if the license is not known or
* has no version
*/
const gchar *
gst_tag_get_license_version (const gchar * license_ref)
{
int idx;
g_return_val_if_fail (license_ref != NULL, NULL);
idx = gst_tag_get_license_idx (license_ref, NULL);
if (idx < 0)
return NULL;
#define LICENSE_FLAG_CC_OR_FSF \
(GST_TAG_LICENSE_CREATIVE_COMMONS_LICENSE|\
GST_TAG_LICENSE_FREE_SOFTWARE_FOUNDATION_LICENSE)
/* e.g. publicdomain isn't versioned */
if (!(licenses[idx].flags & LICENSE_FLAG_CC_OR_FSF))
return NULL;
/* KISS for now... */
if (strstr (licenses[idx].ref, "/1.0/"))
return "1.0";
else if (strstr (licenses[idx].ref, "/2.0/"))
return "2.0";
else if (strstr (licenses[idx].ref, "/2.1/"))
return "2.1";
else if (strstr (licenses[idx].ref, "/2.5/"))
return "2.5";
else if (strstr (licenses[idx].ref, "/3.0/"))
return "3.0";
GST_ERROR ("Could not determine version for ref '%s'", license_ref);
return NULL;
}