[tracker/wip/sam/resource-rebase-5: 9/10] libtracker-extract: Add resource-helpers module

[Sam Thursfield <sthursfield src gnome org>]

commit 8f39545d2e73ebad4c07141b00abe307410c2d3f
Author: Sam Thursfield <sam afuera me uk>
Date:   Mon Apr 18 15:46:51 2016 +0100

    libtracker-extract: Add resource-helpers module
    
    This is factoring common code out of the individual extract modules.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=767472

 src/libtracker-extract/Makefile.am                |    2 +
 src/libtracker-extract/tracker-extract.h          |    1 +
 src/libtracker-extract/tracker-resource-helpers.c |  302 +++++++++++++++++++++
 src/libtracker-extract/tracker-resource-helpers.h |   41 +++
 4 files changed, 346 insertions(+), 0 deletions(-)
---
diff --git a/src/libtracker-extract/Makefile.am b/src/libtracker-extract/Makefile.am
index 8bb6c65..2c1d1fc 100644
--- a/src/libtracker-extract/Makefile.am
+++ b/src/libtracker-extract/Makefile.am
@@ -31,6 +31,8 @@ libtracker_extract_la_SOURCES =  \
        tracker-iptc.h                                 \
        tracker-module-manager.c                       \
        tracker-module-manager.h                       \
+       tracker-resource-helpers.c                     \
+       tracker-resource-helpers.h                     \
        tracker-utils.c                                \
        tracker-utils.h                                \
        tracker-xmp.c                                  \
diff --git a/src/libtracker-extract/tracker-extract.h b/src/libtracker-extract/tracker-extract.h
index 76eb58e..32c40bb 100644
--- a/src/libtracker-extract/tracker-extract.h
+++ b/src/libtracker-extract/tracker-extract.h
@@ -31,6 +31,7 @@
 #include "tracker-module-manager.h"
 #include "tracker-guarantee.h"
 #include "tracker-iptc.h"
+#include "tracker-resource-helpers.h"
 #include "tracker-utils.h"
 #include "tracker-xmp.h"
 
diff --git a/src/libtracker-extract/tracker-resource-helpers.c 
b/src/libtracker-extract/tracker-resource-helpers.c
new file mode 100644
index 0000000..4c33012
--- /dev/null
+++ b/src/libtracker-extract/tracker-resource-helpers.c
@@ -0,0 +1,302 @@
+/*
+ * Copyright (C) 2016, Sam Thursfield <sam afuera me uk>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 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
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ * Boston, MA  02110-1301, USA.
+ */
+
+#include "tracker-resource-helpers.h"
+
+/**
+ * SECTION:tracker-resource-helpers
+ * @title: Resource Helpers
+ * @short_description: Helpers for describing certain common kinds of resource.
+ * @stability: Stable
+ * @include: libtracker-extract/tracker-extract.h
+ *
+ * Some common patterns for resources used in Tracker extractors have helper
+ * functions defined in this module.
+ */
+
+/**
+ * tracker_extract_new_music_artist:
+ * @name: the name of the artist
+ *
+ * Create a new nmm:Artist resource. The URI will be set based on the URI, so
+ * there will only be one resource representing the artist in the Tracker store.
+ *
+ * Returns: a newly allocated #TrackerResource instance, of type nmm:Artist.
+ *
+ * Since: 1.10
+ */
+TrackerResource *
+tracker_extract_new_artist (const char *name)
+{
+       TrackerResource *artist;
+       gchar *uri;
+
+       g_return_val_if_fail (name != NULL, NULL);
+
+       uri = tracker_sparql_escape_uri_printf ("urn:artist:%s", name);
+
+       artist = tracker_resource_new (uri);
+
+       tracker_resource_set_uri (artist, "rdf:type", "nmm:Artist");
+       tracker_resource_set_string (artist, "nmm:artistName", name);
+
+       g_free (uri);
+
+       return artist;
+}
+
+/**
+ * tracker_extract_new_contact:
+ * @fullname: the full name of the contact
+ *
+ * Create a new nco:Contact resource. The URI is based on @fullname, so only
+ * one instance will exist in the Tracker store.
+ *
+ * This is used for describing people or organisations, and can be used with
+ * many fields including nco:artist, nco:creator, nco:publisher, and
+ * nco:representative.
+ *
+ * Returns: a newly allocated #TrackerResource instance, of type nco:Contact
+ *
+ * Since: 1.10
+ */
+TrackerResource *
+tracker_extract_new_contact (const char *fullname)
+{
+       TrackerResource *publisher;
+       gchar *uri;
+
+       g_return_val_if_fail (fullname != NULL, NULL);
+
+       uri = tracker_sparql_escape_uri_printf ("urn:contact:%s", fullname);
+
+       publisher = tracker_resource_new (uri);
+
+       tracker_resource_set_uri (publisher, "rdf:type", "nco:Contact");
+       tracker_resource_set_string (publisher, "nco:fullname", fullname);
+
+       g_free (uri);
+
+       return publisher;
+}
+
+/**
+ * tracker_extract_new_equipment:
+ * @make: (allow none): the manufacturer of the equipment, or %NULL
+ * @model: (allow none): the model name of the equipment, or %NULL
+ *
+ * Create a new nfo:Equipment resource. The URI is based on @make and @model,
+ * so only one instance will exist in the Tracker store. At least one of @make
+ * and @model must be non-%NULL.
+ *
+ * This is useful for describing equipment used to create something, for
+ * example the camera that was used to take a photograph.
+ *
+ * Returns: a newly allocated #TrackerResource instance, of type nfo:Equipment
+ *
+ * Since: 1.10
+ */
+TrackerResource *
+tracker_extract_new_equipment (const char *make,
+                               const char *model)
+{
+       TrackerResource *equipment;
+       gchar *equip_uri;
+
+       g_return_val_if_fail (make != NULL || model != NULL, NULL);
+
+       equip_uri = tracker_sparql_escape_uri_printf ("urn:equipment:%s:%s", make ? make : "", model ? model 
: "");
+
+       equipment = tracker_resource_new (equip_uri);
+       tracker_resource_set_uri (equipment, "rdf:type", "nfo:Equipment");
+
+       if (make) {
+               tracker_resource_set_string (equipment, "nfo:manufacturer", make);
+       }
+
+       if (model) {
+               tracker_resource_set_string (equipment, "nfo:model", model);
+       }
+
+       g_free (equip_uri);
+
+       return equipment;
+}
+
+/**
+ * tracker_extract_new_location:
+ * @street_address: (allow none): main part of postal address, or %NULL
+ * @state: (allow none): regional part of postal address, or %NULL
+ * @city: (allow none): locality part of postal address, or %NULL
+ * @country: (allow none): country of postal address, or %NULL
+ * @gps_altitude: (allow none): altitude (following WGS 84 reference) as a string, or %NULL
+ * @gps_latitude: (allow none): latitude as a string, or %NULL
+ * @gps_longitude: (allow none): longitude as a string, or %NULL
+ *
+ * Create a new slo:GeoLocation resource, with the given postal address and/or
+ * GPS coordinates.
+ *
+ * No validation is done here -- it's up to you to ensure the postal address
+ * and GPS coordinates describe the same thing.
+ *
+ * Returns: a newly allocated #TrackerResource instance, of type slo:GeoLocation
+ *
+ * Since: 1.10
+ */
+TrackerResource *
+tracker_extract_new_location (const char *street_address,
+                              const char *state,
+                              const char *city,
+                              const char *country,
+                              const char *gps_altitude,
+                              const char *gps_latitude,
+                              const char *gps_longitude)
+{
+       TrackerResource *location;
+
+       g_return_val_if_fail (street_address != NULL || state != NULL || city != NULL ||
+                             country != NULL || gps_altitude != NULL ||
+                             gps_latitude != NULL || gps_longitude != NULL, NULL);
+
+       location = tracker_resource_new (NULL);
+       tracker_resource_set_uri (location, "rdf:type", "slo:GeoLocation");
+
+       if (street_address || state || country || city) {
+               TrackerResource *address;
+               gchar *addruri;
+
+               addruri = tracker_sparql_get_uuid_urn ();
+               address = tracker_resource_new (addruri);
+
+               tracker_resource_set_string (address, "rdf:type", "nco:PostalAddress");
+
+               g_free (addruri);
+
+               if (address) {
+                       tracker_resource_set_string (address, "nco:streetAddress", street_address);
+               }
+
+               if (state) {
+                       tracker_resource_set_string (address, "nco:region", state);
+               }
+
+               if (city) {
+                       tracker_resource_set_string (address, "nco:locality", city);
+               }
+
+               if (country) {
+                       tracker_resource_set_string (address, "nco:country", country);
+               }
+
+               tracker_resource_set_relation (location, "slo:postalAddress", address);
+               g_object_unref (address);
+       }
+
+       if (gps_altitude) {
+               tracker_resource_set_string (location, "slo:altitude", gps_altitude);
+       }
+
+       if (gps_latitude) {
+               tracker_resource_set_string (location, "slo:latitude", gps_latitude);
+       }
+
+       if (gps_longitude) {
+               tracker_resource_set_string (location, "slo:longitude", gps_longitude);
+       }
+
+       return location;
+}
+
+/**
+ * tracker_extract_new_music_album_disc:
+ * @album_title: title of the album
+ * @album_artist: (allow none): a #TrackerResource for the album artist, or %NULL
+ * @disc_number: disc number of this disc (the first / only disc in a set should be 1, not 0)
+ *
+ * Create new nmm:MusicAlbumDisc and nmm:MusicAlbum resources. The resources are
+ * given fixed URIs based on @album_title and @disc_number, so they will be
+ * merged with existing entries when serialized to SPARQL and sent to the
+ * Tracker store.
+ *
+ * You can get the album resource from the disc resource by calling:
+ *
+ *     tracker_resource_get_first_relation (album_disc, "nmm:albumDiscAlbum");
+ *
+ * Returns: a newly allocated #TrackerResource instance, of type nmm:MusicAlbumDisc
+ *
+ * Since: 1.10
+ */
+TrackerResource *
+tracker_extract_new_music_album_disc (const char      *album_title,
+                                      TrackerResource *album_artist,
+                                      int              disc_number)
+{
+       char *album_uri, *disc_uri;
+       TrackerResource *album, *album_disc;
+
+       g_return_val_if_fail (album_title != NULL, NULL);
+
+       album_uri = tracker_sparql_escape_uri_printf ("urn:album:%s", album_title);
+       album = tracker_resource_new (album_uri);
+
+       tracker_resource_set_uri (album, "rdf:type", "nmm:MusicAlbum");
+       tracker_resource_set_string (album, "nmm:albumTitle", album_title);
+
+       if (album_artist != NULL) {
+               tracker_resource_add_relation (album, "nmm:albumArtist", album_artist);
+       }
+
+       disc_uri = tracker_sparql_escape_uri_printf ("urn:album-disc:%s:Disc%d", album_title, disc_number);
+       album_disc = tracker_resource_new (disc_uri);
+       tracker_resource_set_int (album_disc, "nmm:setNumber", disc_number > 0 ? disc_number : 1);
+       tracker_resource_add_relation (album_disc, "nmm:albumDiscAlbum", album);
+
+       g_free (disc_uri);
+
+       g_object_unref (album);
+
+       return album_disc;
+}
+
+/**
+ * tracker_extract_new_tag:
+ * @label: the label of the tag
+ *
+ * Create a new nao:Tag resource. The URI will be set based on the tag label,
+ * so there will only be one resource representing the tag in the Tracker store.
+ *
+ * Returns: a newly allocated #TrackerResource instance, of type nao:Tag.
+ *
+ * Since: 1.10
+ */
+TrackerResource *
+tracker_extract_new_tag (const char *label)
+{
+       TrackerResource *tag;
+       char *uri;
+
+       uri = tracker_sparql_escape_uri_printf ("urn:tag:%s", label);
+       tag = tracker_resource_new (uri);
+
+       tracker_resource_set_uri (tag, "rdf:type", "nao:Tag");
+       tracker_resource_set_string (tag, "nao:prefLabel", label);
+
+       g_free (uri);
+       return tag;
+}
diff --git a/src/libtracker-extract/tracker-resource-helpers.h 
b/src/libtracker-extract/tracker-resource-helpers.h
new file mode 100644
index 0000000..2051e8e
--- /dev/null
+++ b/src/libtracker-extract/tracker-resource-helpers.h
@@ -0,0 +1,41 @@
+
+/*
+ * Copyright (C) 2016, Sam Thursfield <sam afuera me uk>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 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
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ * Boston, MA  02110-1301, USA.
+ */
+
+#ifndef __LIBTRACKER_EXTRACT_RESOURCE_HELPERS_H__
+#define __LIBTRACKER_EXTRACT_RESOURCE_HELPERS_H__
+
+#if !defined (__LIBTRACKER_EXTRACT_INSIDE__) && !defined (TRACKER_COMPILATION)
+#error "only <libtracker-extract/tracker-extract.h> must be included directly."
+#endif
+
+#include <libtracker-sparql/tracker-sparql.h>
+
+G_BEGIN_DECLS
+
+TrackerResource *tracker_extract_new_artist (const char *name);
+TrackerResource *tracker_extract_new_contact (const char *fullname);
+TrackerResource *tracker_extract_new_equipment (const char *make, const char *model);
+TrackerResource *tracker_extract_new_location (const char *address, const char *state, const char *city, 
const char *country, const char *gps_altitude, const char *gps_latitude, const char *gps_longitude);
+TrackerResource *tracker_extract_new_music_album_disc (const char *album_title, TrackerResource 
*album_artist, int disc_number);
+TrackerResource *tracker_extract_new_tag (const char *label);
+
+G_END_DECLS
+
+#endif /* __LIBTRACKER_EXTRACT_RESOURCE_HELPERS_H__ */