1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
|
/*
* Copyright (C) 2010, Nokia <ivan.frade@nokia.com>
*
* 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_DATA_H__
#define __LIBTRACKER_EXTRACT_DATA_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
/**
* SECTION:tracker-data
* @title: How to use libtracker-extract
* @short_description: The essentials by example
* @stability: Stable
* @include: libtracker-extract/tracker-extract.h
*
* The libtracker-extract library is the foundation for Tracker
* metadata extraction of embedded data in files.
*
* Tracker comes with extractors written for the most common file
* types (like MP3, JPEG, PNG, etc.), however, for more special cases,
* 3rd party applications may want to write their own plugin to
* extract their own file formats. This documentation describes how to
* do that.
*
* <example>
* <title>Basic extractor example</title>
* An example of how to write an extractor to retrieve PNG embedded
* metadata.
* <programlisting>
* /* Set functions to use to extract different mime types. */
* static TrackerExtractData extract_data[] = {
* { "image/png", extract_png },
* { "sketch/png", extract_png },
* { NULL, NULL }
* };
*
* G_MODULE_EXPORT gboolean
* tracker_extract_get_metadata (const gchar *uri,
* const gchar *mimetype,
* TrackerSparqlBuilder *preupdate,
* TrackerSparqlBuilder *metadata,
* GString *where)
* {
* gint height, width;
*
* /* Do data extraction. */
* height = ...
* width = ...
*
* /* Insert data into TrackerSparqlBuilder object. */
* tracker_sparql_builder_predicate (metadata, "a");
* tracker_sparql_builder_object (metadata, "nfo:Image");
* tracker_sparql_builder_object (metadata, "nmm:Photo");
*
* tracker_sparql_builder_predicate (metadata, "nfo:width");
* tracker_sparql_builder_object_int64 (metadata, width);
*
* tracker_sparql_builder_predicate (metadata, "nfo:height");
* tracker_sparql_builder_object_int64 (metadata, height);
*
* g_free (filename);
*
* /* Were we successful or not? */
* return TRUE;
* }
* </programlisting>
* </example>
*
* NOTE: This example has changed subtly since 0.10. For details see
* tracker_extract_get_metadata().
*
* Since: 0.12
*/
/**
* tracker_extract_get_metadata:
* @uri: a string representing a URI.
* @mimetype: mimetype for the element contained in URI
* @preupdate: used to populate with data updates that
* are a prerequisite for the actual file
* metadata insertion.
* @metadata: used to populate with file metadata predicate/object(s).
* @where: used for optional WHERE patterns
*
* This function must be provided by ALL extractors. This is merely
* the declaration of the function which must be written by each
* extractor.
*
* This is checked by tracker-extract by looking up the symbols for
* each started plugin and making sure this function exists.
*
* The @metadata parameter is a #TrackerSparqlBuilder constructed
* through tracker_sparql_builder_new_embedded_insert(), the subject
* is already set to be the file URN, so implementations of this
* function should just provide predicate/object(s) pairs. the data
* triples contained in there at the end of the function will be
* merged with further file information from miners.
*
* Whenever any of the inserted triples rely on entities that
* should also be provided by this extractor (for example, album
* or artist information from a song), such insertions should be
* added to @preupdate, which is a #TrackerSparqlBuilder constructed.
* through tracker_sparql_builder_new_update().
*
* NOTE: If upgrading from 0.10, this function is replacing the old
* function named tracker_extract_get_data() and has a few subtle
* differences. First there is a return value for success. Second
* there is also a @mimetype argument which should will be passed to
* each extractor.
*
* Returns: %TRUE if the extraction succeeded, %FALSE otherwise.
*
* Since: 0.12
*/
gboolean tracker_extract_get_metadata (const gchar *uri,
const gchar *mimetype,
TrackerSparqlBuilder *preupdate,
TrackerSparqlBuilder *metadata,
GString *where);
G_END_DECLS
#endif /* __LIBTRACKER_EXTRACT_DATA_H__ */
|
