Re: [Multi-valued V2 (grilo) 12/12] core: Add convenience API in GrlMediaFoo

[Iago Toral <itoral igalia com>]

On Tue,  1 Mar 2011 10:50:31 +0100, "Juan A. Suarez Romero" 
<jasuarez igalia com> wrote:
> Add some utilities in GrlMedia clases to handle multi-valued elements
> in those
> keys that could make sense, as well as to handle correlated keys 
> without
> needing to create or handle GrlProperties.
>
> Of course, user can still use GrlProperty and GrlData API to get most
> flexibility.
>
> Signed-off-by: Juan A. Suarez Romero <jasuarez igalia com>
> ---
>  src/data/grl-media-audio.c |  192 
> ++++++++++++++++++++++++++++++++++++++++
>  src/data/grl-media-audio.h |   20 ++++
>  src/data/grl-media-image.c |   57 ++++++++++++
>  src/data/grl-media-image.h |   23 +++++
>  src/data/grl-media-video.c |  134 ++++++++++++++++++++++++++++
>  src/data/grl-media-video.h |   27 ++++++
>  src/data/grl-media.c       |  209
> ++++++++++++++++++++++++++++++++++++++++++++
>  src/data/grl-media.h       |   28 ++++++
>  8 files changed, 690 insertions(+), 0 deletions(-)
>
> diff --git a/src/data/grl-media-audio.c b/src/data/grl-media-audio.c
> index fcdd219..c42cb81 100644
> --- a/src/data/grl-media-audio.c
> +++ b/src/data/grl-media-audio.c
> @@ -163,6 +163,93 @@ grl_media_audio_set_bitrate (GrlMediaAudio
> *data, gint bitrate)
>  }
>
>  /**
> + * grl_media_audio_set_url_data:
> + * @data: the media instance
> + * @url: the audio's url
> + * @mime: the @url mime-type
> + * @bitrate: the @url bitrate, or -1 to ignore
> + *
> + * Set the url of the audio, as well as its mime-type and bitrate.

Sets all the keys related with the URL of an audio resource in one go.

> + **/
> +void
> +grl_media_audio_set_url_data (GrlMediaAudio *data,
> +                              const gchar *url,
> +                              const gchar *mime,
> +                              gint bitrate)
> +{
> +  GrlProperty *prop = grl_property_new_for_key 
> (GRL_METADATA_KEY_URL);
> +  grl_property_set_string (prop, GRL_METADATA_KEY_URL, url);
> +  grl_property_set_string (prop, GRL_METADATA_KEY_MIME, mime);
> +  if (bitrate >= 0) {
> +    grl_property_set_int (prop, GRL_METADATA_KEY_BITRATE, bitrate);
> +  }
> +  grl_data_set_property (GRL_DATA (data), prop, 0);
> +}
> +
> +/**
> + * grl_media_audio_add_artist:
> + * @data: the media instance

We should rename all "data" occurrences by "media". The same for 
GrlMedia and GrlMediaVideo.

> + * @artist: an audio's artist
> + *
> + * Adds a new artist to @data.
> + **/
> +void
> +grl_media_audio_add_artist (GrlMediaAudio *data, const gchar 
> *artist)
> +{
> +  grl_data_add_string (GRL_DATA (data), GRL_METADATA_KEY_ARTIST, 
> artist);
> +}
> +
> +/**
> + * grl_media_audio_add_genre:
> + * @data: the media instance
> + * @genre: an audio's genre
> + *
> + * Adds a new genre to @data.
> + **/
> +void
> +grl_media_audio_add_genre (GrlMediaAudio *data, const gchar *genre)
> +{
> +  grl_data_add_string (GRL_DATA (data), GRL_METADATA_KEY_GENRE, 
> genre);
> +}
> +
> +/**
> + * grl_media_audio_add_lyrics:
> + * @data: the media instance
> + * @lyrics: an audio's lyrics
> + *
> + * Adds a new lyrics to @data.
> + **/
> +void
> +grl_media_audio_add_lyrics (GrlMediaAudio *data, const gchar 
> *lyrics)
> +{
> +  grl_data_add_string (GRL_DATA (data), GRL_METADATA_KEY_LYRICS, 
> lyrics);
> +}
> +
> +/**
> + * grl_media_audio_add_url_data:
> + * @data: the media instance
> + * @url: an audio's url
> + * @mime: the @url mime-type
> + * @bitrate: the @url bitrate, or -1 to ignore
> + *
> + * Adds a new url to @data, as well as its mime-type and bitrate.

Sets all the keys related with the URL of a media resource and
adds it to @data (useful for resources with more than one URL).

> + **/
> +void
> +grl_media_audio_add_url_data (GrlMediaAudio *data,
> +                              const gchar *url,
> +                              const gchar *mime,
> +                              gint bitrate)
> +{
> +  GrlProperty *prop = grl_property_new_for_key 
> (GRL_METADATA_KEY_URL);
> +  grl_property_set_string (prop, GRL_METADATA_KEY_URL, url);
> +  grl_property_set_string (prop, GRL_METADATA_KEY_MIME, mime);
> +  if (bitrate >= 0) {
> +    grl_property_set_int (prop, GRL_METADATA_KEY_BITRATE, bitrate);
> +  }
> +  grl_data_add_property (GRL_DATA (data), prop);
> +}
> +
> +/**
>   * grl_media_audio_get_artist:
>   * @data: the media instance
>   *
> @@ -177,6 +264,25 @@ grl_media_audio_get_artist (GrlMediaAudio *data)
>  }

You missed the description of the "index" parameter in all the get_nth 
APIs below.

>  /**
> + * grl_media_audio_get_artist_nth:
> + * @data: the media instance
> + *
> + * Returns: the n-th artist of the audio
> + */
> +const gchar *
> +grl_media_audio_get_artist_nth (GrlMediaAudio *data, guint index)
> +{
> +  GrlProperty *prop =
> +    grl_data_get_property (GRL_DATA (data), GRL_METADATA_KEY_ARTIST, 
> index);
> +
> +  if (!prop) {
> +    return NULL;
> +  } else {
> +    return grl_property_get_string (prop, GRL_METADATA_KEY_ARTIST);
> +  }
> +}
> +
> +/**
>   * grl_media_audio_get_album:
>   * @data: the media instance
>   *
> @@ -205,6 +311,25 @@ grl_media_audio_get_genre (GrlMediaAudio *data)
>  }
>
>  /**
> + * grl_media_audio_get_genre_nth:
> + * @data: the media instance
> + *
> + * Returns: the n-th genre of the audio
> + */
> +const gchar *
> +grl_media_audio_get_genre_nth (GrlMediaAudio *data, guint index)
> +{
> +  GrlProperty *prop =
> +    grl_data_get_property (GRL_DATA (data), GRL_METADATA_KEY_GENRE, 
> index);
> +
> +  if (!prop) {
> +    return NULL;
> +  } else {
> +    return grl_property_get_string (prop, GRL_METADATA_KEY_GENRE);
> +  }
> +}
> +
> +/**
>   * grl_media_audio_get_lyrics:
>   * @data: the media instance
>   *
> @@ -219,6 +344,25 @@ grl_media_audio_get_lyrics (GrlMediaAudio *data)
>  }
>
>  /**
> + * grl_media_audio_get_lyrics_nth:
> + * @data: the media instance
> + *
> + * Returns: the n-th lyrics of the audio
> + */
> +const gchar *
> +grl_media_audio_get_lyrics_nth (GrlMediaAudio *data, guint index)
> +{
> +  GrlProperty *prop =
> +    grl_data_get_property (GRL_DATA (data), GRL_METADATA_KEY_LYRICS, 
> index);
> +
> +  if (!prop) {
> +    return NULL;
> +  } else {
> +    return grl_property_get_string (prop, GRL_METADATA_KEY_LYRICS);
> +  }
> +}
> +
> +/**
>   * grl_media_audio_get_bitrate:
>   * @data: the media instance
>   *
> @@ -231,3 +375,51 @@ grl_media_audio_get_bitrate (GrlMediaAudio 
> *data)
>  {
>    return grl_data_get_int (GRL_DATA (data), 
> GRL_METADATA_KEY_BITRATE);
>  }
> +
> +/**
> + * grl_media_audio_get_url_data:
> + * @data: the media instance
> + * @mime: (out) (transfer none): the url mime-type, or %NULL to 
> ignore
> + * @bitrate: (out): the url bitrate, or %NULL to ignore
> + *
> + * Returns: the url of the audio, as well as its mime-type and 
> bitrate.

Returns: Gets all the keys related with the URL of an audio resource in 
one go.

> + */
> +const gchar *
> +grl_media_audio_get_url_data (GrlMediaAudio *data,
> +                              gchar **mime,
> +                              gint *bitrate)
> +{
> +  return grl_media_audio_get_url_data_nth (data, 0, mime, bitrate);
> +}
> +
> +/**
> + * grl_media_audio_get_url_data_nth:
> + * @data: the media instance

You're missing the index parameter

> + * @mime: (out) (transfer none): the url mime-type, or %NULL to 
> ignore
> + * @bitrate: (out): the url bitrate, or %NULL to ignore
> + *
> + * Returns: the n-th url of the audio, as well as its mime-type and 
> bitrate.

Returns: Gets all the keys related with the URL number @index of an 
audio resource in one go.

> + */
> +const gchar *
> +grl_media_audio_get_url_data_nth (GrlMediaAudio *data,
> +                                  guint index,
> +                                  gchar **mime,
> +                                  gint *bitrate)
> +{
> +  GrlProperty *prop =
> +    grl_data_get_property (GRL_DATA (data), GRL_METADATA_KEY_URL, 
> index);
> +
> +  if (!prop) {
> +    return NULL;
> +  }
> +
> +  if (mime) {
> +    *mime = (gchar *) grl_property_get_string (prop, 
> GRL_METADATA_KEY_MIME);
> +  }
> +
> +  if (bitrate) {
> +    *bitrate = grl_property_get_int (prop, 
> GRL_METADATA_KEY_BITRATE);
> +  }
> +
> +  return grl_property_get_string (prop, GRL_METADATA_KEY_URL);
> +}
> diff --git a/src/data/grl-media-audio.h b/src/data/grl-media-audio.h
> index d9ee343..f1c0b9d 100644
> --- a/src/data/grl-media-audio.h
> +++ b/src/data/grl-media-audio.h
> @@ -95,16 +95,36 @@ void grl_media_audio_set_lyrics (GrlMediaAudio
> *data, const gchar *lyrics);
>
>  void grl_media_audio_set_bitrate (GrlMediaAudio *data, gint 
> bitrate);
>
> +void grl_media_audio_set_url_data (GrlMediaAudio *data, const gchar
> *url, const gchar *mime, gint bitrate);
> +
> +void grl_media_audio_add_artist (GrlMediaAudio *data, const gchar 
> *artist);
> +
> +void grl_media_audio_add_genre (GrlMediaAudio *data, const gchar 
> *genre);
> +
> +void grl_media_audio_add_lyrics (GrlMediaAudio *data, const gchar 
> *lyrics);
> +
> +void grl_media_audio_add_url_data (GrlMediaAudio *data, const gchar
> *url, const gchar *mime, gint bitrate);
> +
>  const gchar *grl_media_audio_get_artist (GrlMediaAudio *data);
>
> +const gchar *grl_media_audio_get_artist_nth (GrlMediaAudio *data,
> guint index);
> +
>  const gchar *grl_media_audio_get_album (GrlMediaAudio *data);
>
>  const gchar *grl_media_audio_get_genre (GrlMediaAudio *data);
>
> +const gchar *grl_media_audio_get_genre_nth (GrlMediaAudio *data,
> guint index);
> +
>  const gchar *grl_media_audio_get_lyrics (GrlMediaAudio *data);
>
> +const gchar *grl_media_audio_get_lyrics_nth (GrlMediaAudio *data,
> guint index);
> +
>  gint grl_media_audio_get_bitrate (GrlMediaAudio *data);
>
> +const gchar *grl_media_audio_get_url_data (GrlMediaAudio *data,
> gchar **mime, gint *bitrate);
> +
> +const gchar *grl_media_audio_get_url_data_nth (GrlMediaAudio *data,
> guint index, gchar **mime, gint *bitrate);
> +
>  GType grl_media_audio_get_type (void) G_GNUC_CONST;
>
>  GrlMedia *grl_media_audio_new (void);
> diff --git a/src/data/grl-media-image.c b/src/data/grl-media-image.c
> index 2049474..bf4c9d9 100644
> --- a/src/data/grl-media-image.c
> +++ b/src/data/grl-media-image.c
> @@ -162,3 +162,60 @@ grl_media_image_get_height (GrlMediaImage *data)
>  {
>    return grl_data_get_int (GRL_DATA (data), 
> GRL_METADATA_KEY_HEIGHT);
>  }

Same comments as for the audio case.

> +/**
> + * grl_media_image_get_url_data:
(...)
> diff --git a/src/data/grl-media-video.c b/src/data/grl-media-video.c
> index b957dad..f7f7093 100644
> --- a/src/data/grl-media-video.c
> +++ b/src/data/grl-media-video.c
> @@ -193,3 +193,137 @@ grl_media_video_get_framerate (GrlMediaVideo 
> *data)

Same comments as in the audio case.

(...)
>  #endif /* _GRL_MEDIA_VIDEO_H_ */
> diff --git a/src/data/grl-media.c b/src/data/grl-media.c
> index d37bed3..bb8a696 100644
> --- a/src/data/grl-media.c
> +++ b/src/data/grl-media.c
> @@ -112,6 +112,115 @@ grl_media_set_rating (GrlMedia *media, gfloat
> rating, gfloat max)
>  }

Same comments as in the audio case.

Iago