From 4760581e6533ff0853de074ef04968a7ab60f0ca Mon Sep 17 00:00:00 2001 From: "Juan A. Suarez Romero" Date: Wed, 16 Dec 2015 10:41:32 +0100 Subject: doc: update documentation No more GrlMediaFoos. https://bugzilla.gnome.org/show_bug.cgi?id=755551 --- doc/grilo/grilo-docs.sgml | 4 - doc/grilo/grilo-sections.txt | 224 ++++++++++++++---------------------------- doc/grilo/grilo.types | 4 - doc/grilo/plugins-sources.xml | 67 ++++++------- doc/grilo/writing-apps.xml | 21 ++-- src/data/grl-data.c | 10 +- src/data/grl-media.c | 3 +- src/grl-caps.h | 2 +- src/grl-source.h | 2 +- 9 files changed, 120 insertions(+), 217 deletions(-) diff --git a/doc/grilo/grilo-docs.sgml b/doc/grilo/grilo-docs.sgml index 7054e69..4879123 100644 --- a/doc/grilo/grilo-docs.sgml +++ b/doc/grilo/grilo-docs.sgml @@ -95,10 +95,6 @@ - - - - diff --git a/doc/grilo/grilo-sections.txt b/doc/grilo/grilo-sections.txt index c767a41..e15189c 100644 --- a/doc/grilo/grilo-sections.txt +++ b/doc/grilo/grilo-sections.txt @@ -340,31 +340,74 @@ GrlMediaClass GrlMediaSerializeType GrlMediaType grl_media_new +grl_media_audio_new +grl_media_image_new +grl_media_video_new +grl_media_container_new +grl_media_is_audio +grl_media_is_image +grl_media_is_video +grl_media_is_container +grl_media_add_artist grl_media_add_author +grl_media_add_director grl_media_add_external_player grl_media_add_external_url +grl_media_add_genre grl_media_add_keyword +grl_media_add_lyrics +grl_media_add_mb_artist_id +grl_media_add_performer +grl_media_add_producer grl_media_add_region_data grl_media_add_thumbnail grl_media_add_thumbnail_binary grl_media_add_url_data +grl_media_get_album +grl_media_get_artist +grl_media_get_artist_nth grl_media_get_author grl_media_get_author_nth +grl_media_get_bitrate +grl_media_get_camera_model grl_media_get_certificate +grl_media_get_childcount grl_media_get_creation_date grl_media_get_description +grl_media_get_director +grl_media_get_director_nth grl_media_get_duration +grl_media_get_episode +grl_media_get_episode_title +grl_media_get_exposure_time grl_media_get_favourite +grl_media_get_flash_used +grl_media_get_framerate +grl_media_get_genre +grl_media_get_genre_nth +grl_media_get_height grl_media_get_external_url grl_media_get_external_url_nth grl_media_get_id +grl_media_get_iso_speed grl_media_get_keyword grl_media_get_keyword_nth grl_media_get_last_played grl_media_get_last_position grl_media_get_license +grl_media_get_mb_album_id +grl_media_get_mb_artist_id +grl_media_get_mb_artist_id_nth +grl_media_get_mb_recording_id +grl_media_get_mb_track_id grl_media_get_mime grl_media_get_modification_date +grl_media_get_orientation +grl_media_get_original_title +grl_media_get_performer +grl_media_get_performer_nth +grl_media_get_producer +grl_media_get_producer_nth grl_media_get_play_count grl_media_get_player grl_media_get_player_nth @@ -373,6 +416,8 @@ grl_media_get_rating grl_media_get_region grl_media_get_region_data grl_media_get_region_data_nth +grl_media_get_season +grl_media_get_show grl_media_get_site grl_media_get_source grl_media_get_start_time @@ -381,42 +426,71 @@ grl_media_get_thumbnail grl_media_get_thumbnail_binary grl_media_get_thumbnail_binary_nth grl_media_get_thumbnail_nth +grl_media_get_track_number grl_media_get_title grl_media_get_url grl_media_get_url_data grl_media_get_url_data_nth grl_media_get_size +grl_media_get_width grl_media_serialize grl_media_serialize_extended +grl_media_set_album +grl_media_set_artist grl_media_set_author +grl_media_set_bitrate +grl_media_set_camera_model grl_media_set_certificate +grl_media_set_childcount grl_media_set_creation_date grl_media_set_description +grl_media_set_director grl_media_set_duration +grl_media_set_episode +grl_media_set_episode_title +grl_media_set_exposure_time grl_media_set_external_player grl_media_set_external_url grl_media_set_favourite +grl_media_set_flash_used +grl_media_set_framerate +grl_media_set_genre +grl_media_set_height grl_media_set_id +grl_media_set_iso_speed grl_media_set_keyword grl_media_set_last_played grl_media_set_last_position grl_media_set_license +grl_media_set_lyrics +grl_media_set_mb_album_id +grl_media_set_mb_artist_id +grl_media_set_mb_recording_id +grl_media_set_mb_track_id grl_media_set_mime grl_media_set_modification_date +grl_media_set_original_title +grl_media_set_orientation +grl_media_set_performer +grl_media_set_producer grl_media_set_play_count grl_media_set_publication_date grl_media_set_rating grl_media_set_region grl_media_set_region_data +grl_media_set_season +grl_media_set_show grl_media_set_site grl_media_set_source grl_media_set_studio grl_media_set_thumbnail grl_media_set_thumbnail_binary grl_media_set_title +grl_media_set_track_number grl_media_set_url grl_media_set_url_data grl_media_set_size +grl_media_set_width grl_media_unserialize GRL_IS_MEDIA @@ -476,156 +550,6 @@ grl_data_get_type GrlDataPrivate -
-grl-media-box -GrlMediaBox -GrlMediaBox -GrlMediaBoxClass -grl_media_box_new -grl_media_box_get_childcount -grl_media_box_set_childcount - -GRL_IS_MEDIA_BOX -GRL_IS_MEDIA_BOX_CLASS -GRL_MEDIA_BOX -GRL_MEDIA_BOX_CLASS -GRL_MEDIA_BOX_GET_CLASS -GRL_TYPE_MEDIA_BOX -grl_media_box_get_type -
- -
-grl-media-video -GrlMediaVideo -GrlMediaVideo -GrlMediaVideoClass -grl_media_video_new -grl_media_video_add_director -grl_media_video_add_performer -grl_media_video_add_producer -grl_media_video_add_url_data -grl_media_video_get_director -grl_media_video_get_director_nth -grl_media_video_get_episode -grl_media_video_get_episode_title -grl_media_video_get_framerate -grl_media_video_get_height -grl_media_video_get_original_title -grl_media_video_get_performer -grl_media_video_get_performer_nth -grl_media_video_get_producer -grl_media_video_get_producer_nth -grl_media_video_get_season -grl_media_video_get_show -grl_media_video_get_url_data -grl_media_video_get_url_data_nth -grl_media_video_get_width -grl_media_video_set_director -grl_media_video_set_episode -grl_media_video_set_episode_title -grl_media_video_set_framerate -grl_media_video_set_height -grl_media_video_set_original_title -grl_media_video_set_performer -grl_media_video_set_producer -grl_media_video_set_season -grl_media_video_set_show -grl_media_video_set_size -grl_media_video_set_url_data -grl_media_video_set_width - -GRL_IS_MEDIA_VIDEO -GRL_IS_MEDIA_VIDEO_CLASS -GRL_MEDIA_VIDEO -GRL_MEDIA_VIDEO_CLASS -GRL_MEDIA_VIDEO_GET_CLASS -GRL_TYPE_MEDIA_VIDEO -grl_media_video_get_type -
- -
-grl-media-audio -GrlMediaAudio -GrlMediaAudio -GrlMediaAudioClass -grl_media_audio_new -grl_media_audio_add_artist -grl_media_audio_add_genre -grl_media_audio_add_lyrics -grl_media_audio_add_mb_artist_id -grl_media_audio_add_url_data -grl_media_audio_get_album -grl_media_audio_get_artist -grl_media_audio_get_artist_nth -grl_media_audio_get_bitrate -grl_media_audio_get_genre -grl_media_audio_get_genre_nth -grl_media_audio_get_lyrics -grl_media_audio_get_lyrics_nth -grl_media_audio_get_mb_album_id -grl_media_audio_get_mb_artist_id -grl_media_audio_get_mb_artist_id_nth -grl_media_audio_get_mb_recording_id -grl_media_audio_get_mb_track_id -grl_media_audio_get_track_number -grl_media_audio_get_url_data -grl_media_audio_get_url_data_nth -grl_media_audio_set_album -grl_media_audio_set_artist -grl_media_audio_set_bitrate -grl_media_audio_set_genre -grl_media_audio_set_lyrics -grl_media_audio_set_mb_album_id -grl_media_audio_set_mb_artist_id -grl_media_audio_set_mb_recording_id -grl_media_audio_set_mb_track_id -grl_media_audio_set_track_number -grl_media_audio_set_url_data - -GRL_IS_MEDIA_AUDIO -GRL_IS_MEDIA_AUDIO_CLASS -GRL_MEDIA_AUDIO -GRL_MEDIA_AUDIO_CLASS -GRL_MEDIA_AUDIO_GET_CLASS -GRL_TYPE_MEDIA_AUDIO -grl_media_audio_get_type -
- -
-grl-media-image -GrlMediaImage -GrlMediaImage -GrlMediaImageClass -grl_media_image_new -grl_media_image_add_url_data -grl_media_image_get_camera_model -grl_media_image_get_exposure_time -grl_media_image_get_flash_used -grl_media_image_get_height -grl_media_image_get_iso_speed -grl_media_image_get_orientation -grl_media_image_get_url_data -grl_media_image_get_url_data_nth -grl_media_image_get_width -grl_media_image_set_camera_model -grl_media_image_set_exposure_time -grl_media_image_set_flash_used -grl_media_image_set_height -grl_media_image_set_iso_speed -grl_media_image_set_orientation -grl_media_image_set_size -grl_media_image_set_url_data -grl_media_image_set_width - -GRL_IS_MEDIA_IMAGE -GRL_IS_MEDIA_IMAGE_CLASS -GRL_MEDIA_IMAGE -GRL_MEDIA_IMAGE_CLASS -GRL_MEDIA_IMAGE_GET_CLASS -GRL_TYPE_MEDIA_IMAGE -grl_media_image_get_type -
-
grl-metadata-key GrlKeyID diff --git a/doc/grilo/grilo.types b/doc/grilo/grilo.types index 24b9ba2..ce9358c 100644 --- a/doc/grilo/grilo.types +++ b/doc/grilo/grilo.types @@ -12,10 +12,6 @@ grl_data_get_type grl_config_get_type grl_related_keys_get_type grl_media_get_type -grl_media_box_get_type -grl_media_audio_get_type -grl_media_video_get_type -grl_media_image_get_type grl_plugin_get_type grl_source_get_type grl_registry_get_type diff --git a/doc/grilo/plugins-sources.xml b/doc/grilo/plugins-sources.xml index 81f09a9..3939ab5 100644 --- a/doc/grilo/plugins-sources.xml +++ b/doc/grilo/plugins-sources.xml @@ -455,16 +455,16 @@ grl_foo_source_search (GrlSource *source, GrlSourceSearchSpec *ss) Browsing is an interactive process, where users navigate by exploring - these boxes exposed by the media source in hierarchical form. The idea of - browsing a media source is the same as browsing a file system. + these containers exposed by the media source in hierarchical form. The + idea of browsing a media source is the same as browsing a file system. The signature and way of operation of the Browse operation is the same as in the Search operation with one difference: instead of a text parameter with the search keywords, it receives a GrlMedia object representing the container (box) - the user wants to browse. + linkend="GrlMedia">GrlMedia object representing the container the + user wants to browse. @@ -505,11 +505,11 @@ foo_execute_categories_async_cb (gchar *xml, GrlSourceBrowseSpec *bs) } else { /* parse_next parses the next category item in the XML and creates a GrlMedia instance with the data extracted, - which should be of type GrlMediaBox */ + which should be a container */ while (media = parse_next_cat (xml)) bs->callback (bs->source, /* Source emitting the data */ bs->operation_id, /* Operation identifier */ - media, /* The category (box) */ + media, /* The category container */ --count, /* Remaining count */ bs->user_data, /* User data for the callback */ NULL); /* GError instance (if an error occurred) */ @@ -530,9 +530,7 @@ foo_execute_media_async_cb (gchar *xml, GrlSourceBrowseSpec *os) NULL, 0, bs->user_data, NULL); } else { /* parse_next parses the next media item in the XML - and creates a GrlMedia instance with the data extracted, - which should be of type GrlMediaImage, GrlMediaAudio or - GrlMediaVideo */ + and creates a GrlMedia instance with the data extracted */ while (media = parse_next_media (xml)) os->callback (os->source, /* Source emitting the data */ os->operation_id, /* Operation identifier */ @@ -549,10 +547,10 @@ grl_foo_source_browse (GrlSource *source, GrlSourceBrowseSpec *bs) gchar *foo_http_browse: /* We use the names of the categories as their media identifiers */ - box_id = grl_media_get_id (bs->container); + container_id = grl_media_get_id (bs->container); - if (!box_id) { - /* Browsing the root box, the result must be the list of + if (!container_id) { + /* Browsing the root container, the result must be the list of categories provided by the service */ foo_http_browse = g_strdup_printf("http://media.foo.com/category_list", @@ -565,7 +563,7 @@ grl_foo_source_browse (GrlSource *source, GrlSourceBrowseSpec *bs) /* Browsing a specific category */ foo_http_browse = g_strdup_printf("http://media.foo.com/content/%s?offset=%d&count=%d", - box_id, + container_id, grl_operation_options_get_skip (bs), grl_operation_options_get_count (bs)); /* This executes an async http query and then invokes @@ -582,22 +580,20 @@ grl_foo_source_browse (GrlSource *source, GrlSourceBrowseSpec *bs) In the example we are assuming that the content hierarchy only has two levels, the first level exposes a list of categories (each one exposed - as a GrlMediaBox object so the user - knows they can be browsed again), and then a second level with the - contents within these categories, that we assume are all media items, - although in real life they could very well be more GrlMediaBox objects, leading to more - complex hierarchies. + as a container GrlMedia object so the + user knows they can be browsed again), and then a second level with + the contents within these categories, that we assume are all media + items, although in real life they could very well be more containers, + leading to more complex hierarchies. - GrlMediaBox objects returned by a - browse operation can be browsed by clients in future Browse - operations. + Containers returned by a browse operation can be browsed by clients in + future Browse operations. - The input parameter that informs the plugin about the box that should + The input parameter that informs the plugin about the container that should be browsed (bs->container) is of type GrlMediaBox. The plugin developer must + linkend="GrlMedia">GrlMedia. The plugin developer must map that to something the media provider understands. Typically, when GrlMedia objects are returned from a plugin to the client, they are created so their "id" property ( - A GrlMediaBox object with NULL id - always represents the root box/category in the content hierarchy + A GrlMedia object with NULL id always + represents the root container/category in the content hierarchy exposed by the plugin. @@ -746,13 +742,8 @@ grl_foo_source_query (GrlSource *source, GrlSourceQuerySpec *qs) to do in chunks using the idle loop is encouraged. - Creating GrlMedia instances is - easy, depending on the type of media you should instantiate one of the - GrlMedia subclasses (GrlMediaImage, GrlMediaVideo, GrlMediaAudio or GrlMediaBox), and then use the API to set the + Creating GrlMedia instances is easy, + you should instantiate one, and then use the API to set the corresponding data. Check the GrlData hierarchy in the API reference for more details. @@ -876,11 +867,11 @@ grl_foo_source_may_resolve (GrlSource *source, /* We only support audio items */ if (media) { - if (!GRL_IS_MEDIA_AUDIO (media)) + if (!grl_media_is_audio (media)) return FALSE; /* We need artist information available */ - if (grl_media_audio_get_artist (GRL_MEDIA_AUDIO (media)) == NULL) { + if (grl_media_get_artist (media) == NULL) { if (missing_keys) *missing_keys = g_list_add (*missing_keys, GRLKEYID_TO_POINTER (GRL_METADATA_KEY_ARTIST)); @@ -888,7 +879,7 @@ grl_foo_source_may_resolve (GrlSource *source, } /* We need album information available */ - if (grl_media_audio_get_album (GRL_MEDIA_AUDIO (media)) == NULL)) { + if (grl_media_get_album (media) == NULL)) { if (missing_keys) *missing_keys = g_list_add (*missing_keys, GRLKEYID_TO_POINTER (GRL_METADATA_KEY_ALBUM)); @@ -912,8 +903,8 @@ grl_foo_source_resolve (GrlSource *source, const GError *error = NULL; if (contains_key (rs->keys, GRL_METADATA_KEY_THUMBNAIL) { - artist = grl_media_audio_get_artist (GRL_MEDIA_AUDIO (rs->media)); - album = grl_media_audio_get_album (GRL_MEDIA_AUDIO (rs->media)); + artist = grl_media_get_artist (rs->media); + album = grl_media_get_album (rs->media); if (artist && album) { thumb_uri = resolve_thumb_uri (artist, album); grl_media_set_thumbnail (rs->media, thumb_uri); diff --git a/doc/grilo/writing-apps.xml b/doc/grilo/writing-apps.xml index 0e96ac8..3f8a86b 100644 --- a/doc/grilo/writing-apps.xml +++ b/doc/grilo/writing-apps.xml @@ -303,12 +303,11 @@ - Grilo also supports the concept of media container, - represented by the GrlMediaBox subclass. These objects - represent categories or folders that contain other - media objects (including maybe more GrlMediaBox objects), - allowing tree-like hierarchies of content, like the ones - would usually traverse during Browse operations. + Grilo also supports the concept of media container, represented by a + container-type GrlMedia class. These objects represent categories or + folders that contain other media objects (including maybe more container + objects), allowing tree-like hierarchies of content, like the ones would + usually traverse during Browse operations. @@ -516,11 +515,11 @@ Grilo provides application and plugin developers with a high-level APIs to handle certain relations among keys consistently. Continuing with the example of the video resource with multiple URIs, there is - - grl_media_video_add_url_data + + grl_media_add_url_data and - - grl_media_video_get_url_data_nth + + grl_media_get_url_data_nth to add and retrieve all the metadata associated with a particular instance of the video resource (URI, mime-type, framerate, width and height, etc) in one go. @@ -535,7 +534,7 @@ Here is a small program illustrating how get all available URLs from a video resource, as well the corresponding MIME value for each one. - We use GrlRelatedKeys instead of the high-level API from GrlMediaVideo + We use GrlRelatedKeys instead of the high-level API from GrlMedia to illustrate how to use it: diff --git a/src/data/grl-data.c b/src/data/grl-data.c index b453694..db8bdfb 100644 --- a/src/data/grl-data.c +++ b/src/data/grl-data.c @@ -26,13 +26,11 @@ * SECTION:grl-data * @short_description: Low-level class for storing metadata information about * media resources provided by #GrlSource objects. - * @see_also: #GrlMedia, #GrlMediaBox, #GrlMediaVideo, #GrlMediaAudio, - * #GrlMediaImage + * @see_also: #GrlMedia * - * This class acts as a generic metadata dictionary where metadata keys - * and their values can be stored. - * Usually, application and plugin developers would interact with specific - * subclasses of #GrlData, like #GrlMedia or #GrlMediaVideo, which provide + * This class acts as a generic metadata dictionary where metadata keys and + * their values can be stored. Usually, application and plugin developers would + * interact with specific subclass of #GrlData, #GrlMedia, which provide * specific API to manipulate well known attributes of these media types. */ diff --git a/src/data/grl-media.c b/src/data/grl-media.c index 456db54..deaed68 100644 --- a/src/data/grl-media.c +++ b/src/data/grl-media.c @@ -25,8 +25,7 @@ /** * SECTION:grl-media * @short_description: A multimedia data transfer object - * @see_also: #GrlData, #GrlMediaBox, #GrlMediaVideo, #GrlMediaAudio, - * #GrlMediaImage + * @see_also: #GrlData * * This high level class represents a multimedia item. It has methods to * set and get properties like author, title, description, and so on. diff --git a/src/grl-caps.h b/src/grl-caps.h index e3298f7..8dbdbdc 100644 --- a/src/grl-caps.h +++ b/src/grl-caps.h @@ -69,7 +69,7 @@ typedef struct { /** * GrlTypeFilter: - * @GRL_TYPE_FILTER_NONE: allow no content (only #GrlMediaBox) + * @GRL_TYPE_FILTER_NONE: allow no content (only containers) * @GRL_TYPE_FILTER_AUDIO: allow audio content * @GRL_TYPE_FILTER_VIDEO: allow video content * @GRL_TYPE_FILTER_IMAGE: allow image content diff --git a/src/grl-source.h b/src/grl-source.h index f8e9ccb..68c1342 100644 --- a/src/grl-source.h +++ b/src/grl-source.h @@ -129,7 +129,7 @@ typedef enum { /** * GrlSourceChangeType: * @GRL_CONTENT_CHANGED: content has changed. It is used when any property of - * #GrlMedia has changed, or in case of #GrlMediaBox, if several children have + * #GrlMedia has changed, or in case of containers, if several children have * been added and removed. * @GRL_CONTENT_ADDED: new content has been added. * @GRL_CONTENT_REMOVED: content has been removed -- cgit v1.2.3