2
* Copyright (C) 2010, 2011 Igalia S.L.
4
* Contact: Iago Toral Quiroga <itoral@igalia.com>
6
* This library is free software; you can redistribute it and/or
7
* modify it under the terms of the GNU Lesser General Public License
8
* as published by the Free Software Foundation; version 2.1 of
9
* the License, or (at your option) any later version.
11
* This library is distributed in the hope that it will be useful, but
12
* WITHOUT ANY WARRANTY; without even the implied warranty of
13
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14
* Lesser General Public License for more details.
16
* You should have received a copy of the GNU Lesser General Public
17
* License along with this library; if not, write to the Free Software
18
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
23
#if !defined (_GRILO_H_INSIDE_) && !defined (GRILO_COMPILATION)
24
#error "Only <grilo.h> can be included directly."
27
#ifndef _GRL_METADATA_SOURCE_H_
28
#define _GRL_METADATA_SOURCE_H_
30
#include <grl-media-plugin.h>
31
#include <grl-metadata-key.h>
32
#include <grl-media.h>
33
#include <grl-definitions.h>
36
#include <glib-object.h>
40
#define GRL_TYPE_METADATA_SOURCE \
41
(grl_metadata_source_get_type ())
43
#define GRL_METADATA_SOURCE(obj) \
44
(G_TYPE_CHECK_INSTANCE_CAST ((obj), \
45
GRL_TYPE_METADATA_SOURCE, \
48
#define GRL_IS_METADATA_SOURCE(obj) \
49
(G_TYPE_CHECK_INSTANCE_TYPE ((obj), \
50
GRL_TYPE_METADATA_SOURCE))
52
#define GRL_METADATA_SOURCE_CLASS(klass) \
53
(G_TYPE_CHECK_CLASS_CAST((klass), \
54
GRL_TYPE_METADATA_SOURCE, \
55
GrlMetadataSourceClass))
57
#define GRL_IS_METADATA_SOURCE_CLASS(klass) \
58
(G_TYPE_CHECK_CLASS_TYPE((klass), \
59
GRL_TYPE_METADATA_SOURCE))
61
#define GRL_METADATA_SOURCE_GET_CLASS(obj) \
62
(G_TYPE_INSTANCE_GET_CLASS ((obj), \
63
GRL_TYPE_METADATA_SOURCE, \
64
GrlMetadataSourceClass))
67
* GrlMetadataResolutionFlags:
68
* @GRL_RESOLVE_NORMAL: Normal mode.
69
* @GRL_RESOLVE_FULL: Try other plugins if necessary.
70
* @GRL_RESOLVE_IDLE_RELAY: Use idle loop to relay results.
71
* @GRL_RESOLVE_FAST_ONLY: Only resolve fast metadata keys.
73
* GrlMetadata resolution flags
76
GRL_RESOLVE_NORMAL = 0, /* Normal mode */
77
GRL_RESOLVE_FULL = (1 << 0), /* Try other plugins if necessary */
78
GRL_RESOLVE_IDLE_RELAY = (1 << 1), /* Use idle loop to relay results */
79
GRL_RESOLVE_FAST_ONLY = (1 << 2) /* Only resolve fast metadata keys */
80
} GrlMetadataResolutionFlags;
83
* GrlMetadataWritingFlags:
84
* @GRL_WRITE_NORMAL: Normal mode.
85
* @GRL_WRITE_FULL: Try other plugins if necessary.
87
* Flags for metadata writing operations.
90
GRL_WRITE_NORMAL = 0, /* Normal mode */
91
GRL_WRITE_FULL = (1 << 0) /* Try other plugins if necessary */
92
} GrlMetadataWritingFlags;
94
/* GrlMetadataSource object */
96
typedef struct _GrlMetadataSource GrlMetadataSource;
97
typedef struct _GrlMetadataSourcePrivate GrlMetadataSourcePrivate;
99
struct _GrlMetadataSource {
101
GrlMediaPlugin parent;
104
GrlMetadataSourcePrivate *priv;
106
gpointer _grl_reserved[GRL_PADDING];
109
/* Callbacks for GrlMetadataSource class */
112
* GrlMetadataSourceResolveCb:
113
* @source: a metadata source
114
* @operation_id: operation identifier
115
* @media: (transfer full): a #GrlMedia transfer object
116
* @user_data: user data passed to grl_metadata_source_resolve()
117
* @error: (type uint): possible #GError generated when resolving the metadata
119
* Prototype for the callback passed to grl_metadata_source_resolve()
121
typedef void (*GrlMetadataSourceResolveCb) (GrlMetadataSource *source,
125
const GError *error);
128
* GrlMetadataSourceSetMetadataCb:
129
* @source: a metadata source
130
* @media: (transfer full): a #GrlMedia transfer object
131
* @failed_keys: (element-type GObject.ParamSpec) (transfer container): #GList of
132
* keys that could not be updated, if any
133
* @user_data: user data passed to grl_metadata_source_set_metadata()
134
* @error: (type uint): possible #GError generated when updating the metadata
136
* Prototype for the callback passed to grl_metadata_source_set_metadata()
138
typedef void (*GrlMetadataSourceSetMetadataCb) (GrlMetadataSource *source,
142
const GError *error);
144
/* Types for GrlMetadataSource */
147
* GrlMetadataSourceResolveSpec:
148
* @source: a metadata source
149
* @resolve_id: operation identifier
150
* @keys: the #GList of #GrlKeyID to fetch and store
151
* @media: a #GrlMedia transfer object
152
* @flags: bitwise mask of #GrlMetadataResolutionFlags with the resolution
154
* @callback: the callback passed to grl_metadata_source_resolve()
155
* @user_data: user data passed to grl_metadata_source_resolve()
157
* Represents the closure used by the derived objects to fetch, store and
158
* return the transfer object to the client's code.
161
GrlMetadataSource *source;
165
GrlMetadataResolutionFlags flags;
166
GrlMetadataSourceResolveCb callback;
170
gpointer _grl_reserved[GRL_PADDING - 1];
171
} GrlMetadataSourceResolveSpec;
174
* GrlMetadataSourceSetMetadataSpec:
175
* @source: a metadata source
176
* @media: a #GrlMedia transfer object
177
* @keys: List of keys to be stored/updated.
178
* @flags: Flags to control specific bahviors of the set metadata operation.
179
* @callback: the callback passed to grl_metadata_source_set_metadata()
180
* @user_data: user data passed to grl_metadata_source_set_metadata()
181
* @failed_keys: for internal use of the framework only.
183
* Represents the closure used by the derived objects to operate.
186
GrlMetadataSource *source;
189
GrlMetadataWritingFlags flags;
190
GrlMetadataSourceSetMetadataCb callback;
195
gpointer _grl_reserved[GRL_PADDING];
196
} GrlMetadataSourceSetMetadataSpec;
200
* @GRL_OP_NONE: no operation is supported
201
* @GRL_OP_METADATA: Fetch specific keys of metadata based on the media id.
202
* @GRL_OP_RESOLVE: Fetch specific keys of metadata based on other metadata.
203
* @GRL_OP_BROWSE: Retrieve complete sets of #GrlMedia
204
* @GRL_OP_SEARCH: Look up for #GrlMedia given a search text
205
* @GRL_OP_QUERY: Look up for #GrlMedia give a service specific query
206
* @GRL_OP_STORE: Store content in a service
207
* @GRL_OP_STORE_PARENT: Store content as child of a certian parent category.
208
* @GRL_OP_REMOVE: Remove content from a service.
209
* @GRL_OP_SET_METADATA: Update metadata of a #GrlMedia in a service.
210
* @GRL_OP_MEDIA_FROM_URI: Create a #GrlMedia instance from an URI
211
* representing a media resource.
212
* @GRL_OP_NOTIFY_CHANGE: Notify about changes in the #GrlMediaSource.
214
* Bitwise flags which reflect the kind of operations that a
215
* #GrlMediaPlugin supports.
220
GRL_OP_RESOLVE = 1 << 1,
221
GRL_OP_BROWSE = 1 << 2,
222
GRL_OP_SEARCH = 1 << 3,
223
GRL_OP_QUERY = 1 << 4,
224
GRL_OP_STORE = 1 << 5,
225
GRL_OP_STORE_PARENT = 1 << 6,
226
GRL_OP_REMOVE = 1 << 7,
227
GRL_OP_SET_METADATA = 1 << 8,
228
GRL_OP_MEDIA_FROM_URI = 1 << 9,
229
GRL_OP_NOTIFY_CHANGE = 1 << 10
232
/* GrlMetadataSource class */
234
typedef struct _GrlMetadataSourceClass GrlMetadataSourceClass;
237
* GrlMetadataSourceClass:
238
* @parent_class: the parent class structure
239
* @operation_id: operation identifier
240
* @supported_operations: the operations that can be called
241
* @supported_keys: the list of keys that can be handled
242
* @slow_keys: the list of slow keys that can be fetched
243
* @key_depends: a deprecated vmethod that will be removed in the future
244
* @writable_keys: the list of keys which value can be written
245
* @resolve: resolve the metadata of a given transfer object
246
* @set_metadata: update metadata values for a given object in a
248
* @may_resolve: return FALSE if it can be known without blocking that @key_id
249
* cannot be resolved for @media, TRUE otherwise. Optionally fill @missing_keys
250
* with a list of keys that would be needed to resolve. See
251
* grl_metadata_source_may_resolve().
252
* @cancel: cancel the current operation
254
* Grilo MetadataSource class. Override the vmethods to implement the
255
* element functionality.
257
struct _GrlMetadataSourceClass {
259
GrlMediaPluginClass parent_class;
263
GrlSupportedOps (*supported_operations) (GrlMetadataSource *source);
265
const GList * (*supported_keys) (GrlMetadataSource *source);
267
const GList * (*slow_keys) (GrlMetadataSource *source);
269
const GList * (*key_depends) (GrlMetadataSource *source, GrlKeyID key_id);
271
const GList * (*writable_keys) (GrlMetadataSource *source);
273
void (*resolve) (GrlMetadataSource *source,
274
GrlMetadataSourceResolveSpec *rs);
276
void (*set_metadata) (GrlMetadataSource *source,
277
GrlMetadataSourceSetMetadataSpec *sms);
279
gboolean (*may_resolve) (GrlMetadataSource *source, GrlMedia *media,
280
GrlKeyID key_id, GList **missing_keys);
282
void (*cancel) (GrlMetadataSource *source, guint operation_id);
285
gpointer _grl_reserved[GRL_PADDING - 3];
290
GType grl_metadata_source_get_type (void);
292
GrlSupportedOps grl_metadata_source_supported_operations (GrlMetadataSource *source);
294
const GList *grl_metadata_source_supported_keys (GrlMetadataSource *source);
296
const GList *grl_metadata_source_slow_keys (GrlMetadataSource *source);
298
GList *grl_metadata_source_filter_supported (GrlMetadataSource *source,
300
gboolean return_filtered);
302
GList *grl_metadata_source_filter_slow (GrlMetadataSource *source,
304
gboolean return_filtered);
306
GList *grl_metadata_source_filter_writable (GrlMetadataSource *source,
308
gboolean return_filtered);
310
const GList *grl_metadata_source_key_depends (GrlMetadataSource *source,
313
const GList *grl_metadata_source_writable_keys (GrlMetadataSource *source);
315
gboolean grl_metadata_source_may_resolve (GrlMetadataSource *source,
318
GList **missing_keys);
320
guint grl_metadata_source_resolve (GrlMetadataSource *source,
323
GrlMetadataResolutionFlags flags,
324
GrlMetadataSourceResolveCb callback,
327
GrlMedia *grl_metadata_source_resolve_sync (GrlMetadataSource *source,
330
GrlMetadataResolutionFlags flags,
333
G_GNUC_DEPRECATED void grl_metadata_source_set_operation_data (GrlMetadataSource *source,
337
G_GNUC_DEPRECATED gpointer grl_metadata_source_get_operation_data (GrlMetadataSource *source,
340
void grl_metadata_source_set_metadata (GrlMetadataSource *source,
343
GrlMetadataWritingFlags flags,
344
GrlMetadataSourceSetMetadataCb callback,
347
GList *grl_metadata_source_set_metadata_sync (GrlMetadataSource *source,
350
GrlMetadataWritingFlags flags,
353
G_GNUC_DEPRECATED void grl_metadata_source_cancel (GrlMetadataSource *source,
356
const gchar *grl_metadata_source_get_id (GrlMetadataSource *source);
358
const gchar *grl_metadata_source_get_name (GrlMetadataSource *source);
360
const gchar *grl_metadata_source_get_description (GrlMetadataSource *source);
364
#endif /* _GRL_METADATA_SOURCE_H_ */