Commit 9f4219e7 authored by Philip Withnall's avatar Philip Withnall Committed by Philip Withnall

Add full documentation for all public symbols exposed by the library,

2008-01-15  Philip Withnall  <pwithnall@svn.gnome.org>

	* Makefile.am:
	* configure.in:
	* docs/reference/Makefile.am:
	* docs/reference/totem-pl-parser-docs.sgml:
	* docs/reference/totem-pl-parser-sections.txt:
	* docs/reference/totem-pl-parser.types:
	* docs/reference/version.xml.in:
	* plparse/totem-disc.c:
	* plparse/totem-disc.h:
	* plparse/totem-pl-parser.c: (totem_pl_parser_class_init),
	(totem_pl_parser_num_entries):
	* plparse/totem-pl-parser.h: Add full documentation for all
	public symbols exposed by the library, excluding code samples
	for the playlist parser. (Helps: #507995)


svn path=/trunk/; revision=37
parent 537f7777
2008-01-15 Philip Withnall <pwithnall@svn.gnome.org>
* Makefile.am:
* configure.in:
* docs/reference/Makefile.am:
* docs/reference/totem-pl-parser-docs.sgml:
* docs/reference/totem-pl-parser-sections.txt:
* docs/reference/totem-pl-parser.types:
* docs/reference/version.xml.in:
* plparse/totem-disc.c:
* plparse/totem-disc.h:
* plparse/totem-pl-parser.c: (totem_pl_parser_class_init),
(totem_pl_parser_num_entries):
* plparse/totem-pl-parser.h: Add full documentation for all
public symbols exposed by the library, excluding code samples
for the playlist parser. (Helps: #507995)
2008-01-09 Philip Withnall <pwithnall@svn.gnome.org>
* plparse/totem-disc.c: (cd_cache_has_medium):
......
......@@ -19,4 +19,4 @@ DISTCLEANFILES = intltool-extract intltool-merge intltool-update \
pkgconfigdir = $(libdir)/pkgconfig
pkgconfig_DATA = totem-plparser.pc totem-plparser-mini.pc
DISTCHECK_CONFIGURE_FLAGS = --disable-scrollkeeper
DISTCHECK_CONFIGURE_FLAGS = --disable-scrollkeeper --enable-gtk-doc
......@@ -116,6 +116,7 @@ plparse/totem-pl-parser-features.h
po/Makefile.in
docs/Makefile
docs/reference/Makefile
docs/reference/version.xml
])
AC_MSG_NOTICE([totem-pl-parser was configured with the following options:])
......
......@@ -74,7 +74,7 @@ HTML_IMAGES=
# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
content_files=
content_files=version.xml
# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
# These files must be listed here *and* in content_files
......@@ -94,4 +94,4 @@ include $(top_srcdir)/gtk-doc.make
# Other files to distribute
# e.g. EXTRA_DIST += version.xml.in
EXTRA_DIST +=
EXTRA_DIST += version.xml.in
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY version SYSTEM "version.xml">
]>
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
<bookinfo>
<title>totem-pl-parser Reference Manual</title>
<releaseinfo>
for totem-pl-parser &version;
</releaseinfo>
</bookinfo>
<chapter>
<title>API Reference</title>
<xi:include href="xml/totem-pl-parser.xml"/>
<xi:include href="xml/totem-disc.xml"/>
</chapter>
</book>
<SECTION>
<FILE>totem-pl-parser</FILE>
TotemPlParserResult
TOTEM_PL_PARSER_FIELD_URL
TOTEM_PL_PARSER_FIELD_GENRE
TOTEM_PL_PARSER_FIELD_TITLE
TOTEM_PL_PARSER_FIELD_AUTHOR
TOTEM_PL_PARSER_FIELD_BASE
TOTEM_PL_PARSER_FIELD_VOLUME
TOTEM_PL_PARSER_FIELD_AUTOPLAY
TOTEM_PL_PARSER_FIELD_DURATION
TOTEM_PL_PARSER_FIELD_STARTTIME
TOTEM_PL_PARSER_FIELD_ENDTIME
TOTEM_PL_PARSER_FIELD_COPYRIGHT
TOTEM_PL_PARSER_FIELD_ABSTRACT
TOTEM_PL_PARSER_FIELD_DESCRIPTION
TOTEM_PL_PARSER_FIELD_SUMMARY
TOTEM_PL_PARSER_FIELD_MOREINFO
TOTEM_PL_PARSER_FIELD_SCREENSIZE
TOTEM_PL_PARSER_FIELD_UI_MODE
TOTEM_PL_PARSER_FIELD_PUB_DATE
TOTEM_PL_PARSER_FIELD_FILESIZE
TOTEM_PL_PARSER_FIELD_LANGUAGE
TOTEM_PL_PARSER_FIELD_CONTACT
TOTEM_PL_PARSER_FIELD_IMAGE_URL
TOTEM_PL_PARSER_FIELD_IS_PLAYLIST
TotemPlParserType
TotemPlParserError
TotemPlParserIterFunc
totem_pl_parser_parse_duration
totem_pl_parser_parse_date
totem_pl_parser_resolve_url
totem_pl_parser_write
totem_pl_parser_write_with_title
totem_pl_parser_add_ignored_scheme
totem_pl_parser_add_ignored_mimetype
totem_pl_parser_parse
totem_pl_parser_parse_with_base
totem_pl_parser_new
<SUBSECTION Standard>
TOTEM_PL_PARSER
TOTEM_IS_PL_PARSER
TOTEM_TYPE_PL_PARSER
totem_pl_parser_get_type
TOTEM_PL_PARSER_CLASS
TOTEM_IS_PL_PARSER_CLASS
totem_pl_parser_error_quark
TOTEM_PL_PARSER_ERROR
<SUBSECTION Private>
TotemPlParser
TotemPlParserClass
TotemPlParserPrivate
entry_parsed
playlist_started
playlist_ended
</SECTION>
<SECTION>
<FILE>totem-disc</FILE>
TotemDiscMediaType
totem_cd_detect_type
totem_cd_detect_type_with_url
totem_cd_detect_type_from_dir
totem_cd_get_human_readable_name
totem_cd_mrl_from_type
totem_cd_has_medium
<SUBSECTION Standard>
MediaType
</SECTION>
@TOTEM_PL_PARSER_VERSION_MAJOR@.@TOTEM_PL_PARSER_VERSION_MINOR@.@TOTEM_PL_PARSER_VERSION_MICRO@
......@@ -27,6 +27,16 @@
*
*/
/**
* SECTION:totem-disc
* @short_description: disc utility functions
* @stability: Stable
* @include: totem-disc.h
*
* This file has various different disc utility functions for getting
* the media types and labels of discs.
**/
#include "config.h"
#include <fcntl.h>
......@@ -685,6 +695,17 @@ cd_cache_disc_is_dvd (CdCache *cache,
return MEDIA_TYPE_DATA;
}
/**
* totem_cd_mrl_from_type:
* @scheme: a scheme (e.g. "dvd")
* @dir: a directory URI
*
* Builds an MRL using the scheme @scheme and the given URI @dir,
* taking the filename from the URI if it's a <filename>file://</filename> and just
* using the whole URI otherwise.
*
* Return value: a newly-allocated string containing the MRL
**/
char *
totem_cd_mrl_from_type (const char *scheme, const char *dir)
{
......@@ -720,6 +741,18 @@ totem_cd_dir_get_parent (const char *dir)
return parent;
}
/**
* totem_cd_detect_type_from_dir:
* @dir: a directory URI
* @url: return location for the disc's MRL, or %NULL
* @error: return location for a #GError, or %NULL
*
* Detects the disc's type, given its mount directory URI. If
* a string pointer is passed to @url, it will return the disc's
* MRL as from totem_cd_mrl_from_type().
*
* Return value: #TotemDiscMediaType corresponding to the disc's type, or #MEDIA_TYPE_ERROR on failure
**/
TotemDiscMediaType
totem_cd_detect_type_from_dir (const char *dir, char **url, GError **error)
{
......@@ -771,6 +804,18 @@ totem_cd_detect_type_from_dir (const char *dir, char **url, GError **error)
return type;
}
/**
* totem_cd_detect_type_with_url:
* @device: a device node path
* @url: return location for the disc's MRL, or %NULL
* @error: return location for a #GError, or %NULL
*
* Detects the disc's type, given its device node path. If
* a string pointer is passed to @url, it will return the disc's
* MRL as from totem_cd_mrl_from_type().
*
* Return value: #TotemDiscMediaType corresponding to the disc's type, or #MEDIA_TYPE_ERROR on failure
**/
TotemDiscMediaType
totem_cd_detect_type_with_url (const char *device,
char **url,
......@@ -827,6 +872,15 @@ totem_cd_detect_type_with_url (const char *device,
return type;
}
/**
* totem_cd_detect_type:
* @device: a device node path
* @error: return location for a #GError, or %NULL
*
* Detects the disc's type, given its device node path.
*
* Return value: #TotemDiscMediaType corresponding to the disc's type, or #MEDIA_TYPE_ERROR on failure
**/
TotemDiscMediaType
totem_cd_detect_type (const char *device,
GError **error)
......@@ -834,6 +888,14 @@ totem_cd_detect_type (const char *device,
return totem_cd_detect_type_with_url (device, NULL, error);
}
/**
* totem_cd_has_medium:
* @device: a device node path
*
* Returns whether the disc has a physical medium.
*
* Return value: %TRUE if the disc physically exists
**/
gboolean
totem_cd_has_medium (const char *device)
{
......@@ -849,6 +911,15 @@ totem_cd_has_medium (const char *device)
return retval;
}
/**
* totem_cd_get_human_readable_name:
* @type: a #TotemDiscMediaType
*
* Returns the human-readable name for the given
* #TotemDiscMediaType.
*
* Return value: the disc media type's readable name, which must not be freed, or %NULL for unhandled media types
**/
const char *
totem_cd_get_human_readable_name (TotemDiscMediaType type)
{
......
......@@ -26,8 +26,21 @@
G_BEGIN_DECLS
/**
* TotemDiscMediaType:
* @MEDIA_TYPE_ERROR: there was an error determining the media's type
* @MEDIA_TYPE_DATA: data disc
* @MEDIA_TYPE_CDDA: audio CD
* @MEDIA_TYPE_VCD: video CD
* @MEDIA_TYPE_DVD: video DVD
* @MEDIA_TYPE_DVB: digital television
* @MEDIA_TYPE_NUM_TYPES: the number of supported media types
*
* Gives the media type of a disc, or %MEDIA_TYPE_ERROR if the media type
* could not be determined.
**/
typedef enum {
MEDIA_TYPE_ERROR = -1, /* error */
MEDIA_TYPE_ERROR = -1,
MEDIA_TYPE_DATA = 1,
MEDIA_TYPE_CDDA,
MEDIA_TYPE_VCD,
......
......@@ -18,9 +18,18 @@
Boston, MA 02111-1307, USA.
Authors: Bastien Nocera <hadess@hadess.net>
*/
/**
* SECTION:totem-pl-parser
* @short_description: playlist parser
* @stability: Stable
* @include: totem-pl-parser.h
*
* #TotemPlParser is a general-purpose playlist parser and writer, with
* support for several different types of playlist.
**/
#include "config.h"
#include <string.h>
......@@ -158,6 +167,13 @@ totem_pl_parser_class_init (TotemPlParserClass *klass)
object_class->get_property = totem_pl_parser_get_property;
/* Properties */
/**
* TotemPlParser:recurse:
*
* If %TRUE, the parser will recursively fetch playlists linked to by
* the current one.
**/
g_object_class_install_property (object_class,
PROP_RECURSE,
g_param_spec_boolean ("recurse",
......@@ -166,6 +182,11 @@ totem_pl_parser_class_init (TotemPlParserClass *klass)
TRUE,
G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
/**
* TotemPlParser:debug:
*
* If %TRUE, the parser will output debug information.
**/
g_object_class_install_property (object_class,
PROP_DEBUG,
g_param_spec_boolean ("debug",
......@@ -174,6 +195,12 @@ totem_pl_parser_class_init (TotemPlParserClass *klass)
FALSE,
G_PARAM_READWRITE));
/**
* TotemPlParser:force:
*
* If %TRUE, the parser will attempt to parse a playlist, even if it
* appears to be unsupported (usually because of its filename extension).
**/
g_object_class_install_property (object_class,
PROP_FORCE,
g_param_spec_boolean ("force",
......@@ -182,6 +209,13 @@ totem_pl_parser_class_init (TotemPlParserClass *klass)
FALSE,
G_PARAM_READWRITE));
/**
* TotemPlParser:disable-unsafe:
*
* If %TRUE, the parser will not parse unsafe locations, such as local devices
* and local files if the playlist isn't local. This is useful if the library
* is parsing a playlist from a remote location such as a website.
**/
g_object_class_install_property (object_class,
PROP_DISABLE_UNSAFE,
g_param_spec_boolean ("disable-unsafe",
......@@ -430,7 +464,7 @@ totem_pl_parser_init_i18n (void)
}
/**
* totem_pl_parser_new
* totem_pl_parser_new:
*
* Creates a #TotemPlParser object.
*
......@@ -443,6 +477,14 @@ totem_pl_parser_new (void)
return TOTEM_PL_PARSER (g_object_new (TOTEM_TYPE_PL_PARSER, NULL));
}
/**
* totem_pl_parser_playlist_end:
* @parser: a #TotemPlParser
* @playlist_uri: the playlist URI
*
* Emits the #TotemPlParser::playlist-ended signal on @parser for
* the playlist @playlist_uri.
**/
void
totem_pl_parser_playlist_end (TotemPlParser *parser, const char *playlist_uri)
{
......@@ -544,6 +586,14 @@ my_gnome_vfs_get_mime_type_with_data (const char *uri, gpointer *data, TotemPlPa
return g_strdup (mimetype);
}
/**
* totem_pl_parser_base_url:
* @url: a URI
*
* Returns the parent URI of @url.
*
* Return value: a newly-allocated string containing @url's parent URI, or %NULL
**/
char *
totem_pl_parser_base_url (const char *url)
{
......@@ -569,6 +619,15 @@ totem_pl_parser_base_url (const char *url)
return base;
}
/**
* totem_pl_parser_line_is_empty:
* @line: a playlist line to check
*
* Checks to see if the given string line is empty or %NULL,
* counting tabs and spaces, but not newlines, as "empty".
*
* Return value: %TRUE if @line is empty
**/
gboolean
totem_pl_parser_line_is_empty (const char *line)
{
......@@ -584,6 +643,16 @@ totem_pl_parser_line_is_empty (const char *line)
return TRUE;
}
/**
* totem_pl_parser_write_string:
* @handle: a #GnomeVFSHandle to an open file
* @buf: the string buffer to write out
* @error: return location for a #GError, or %NULL
*
* Writes the string @buf out to the file specified by @handle.
*
* Return value: %TRUE on success
**/
gboolean
totem_pl_parser_write_string (GnomeVFSHandle *handle, const char *buf, GError **error)
{
......@@ -593,6 +662,17 @@ totem_pl_parser_write_string (GnomeVFSHandle *handle, const char *buf, GError **
return totem_pl_parser_write_buffer (handle, buf, len, error);
}
/**
* totem_pl_parser_write_buffer:
* @handle: a #GnomeVFSHandle to an open file
* @buf: the string buffer to write out
* @len: the length of the string to write out
* @error: return location for a #GError, or %NULL
*
* Writes @len bytes of @buf to the file specified by @handle.
*
* Return value: %TRUE on success
**/
gboolean
totem_pl_parser_write_buffer (GnomeVFSHandle *handle, const char *buf, guint len, GError **error)
{
......@@ -613,6 +693,18 @@ totem_pl_parser_write_buffer (GnomeVFSHandle *handle, const char *buf, guint len
return TRUE;
}
/**
* totem_pl_parser_num_entries:
* @parser: a #TotemPlParser
* @model: a #GtkTreeModel
* @func: a pointer to a #TotemPlParserIterFunc callback function
* @user_data: a pointer to be passed to each call of @func
*
* Returns the number of entries in @parser's playlist, and calls
* @func for each valid entry in the playlist.
*
* Return value: the number of entries in the playlist
**/
int
totem_pl_parser_num_entries (TotemPlParser *parser, GtkTreeModel *model,
TotemPlParserIterFunc func, gpointer user_data)
......@@ -628,7 +720,7 @@ totem_pl_parser_num_entries (TotemPlParser *parser, GtkTreeModel *model,
char *url, *title;
gboolean custom_title;
if (gtk_tree_model_iter_nth_child (model, &iter, NULL, i -1) == FALSE)
if (gtk_tree_model_iter_nth_child (model, &iter, NULL, i - 1) == FALSE)
return i - ignored;
func (model, &iter, &url, &title, &custom_title, user_data);
......@@ -642,6 +734,19 @@ totem_pl_parser_num_entries (TotemPlParser *parser, GtkTreeModel *model,
return num_entries - ignored;
}
/**
* totem_pl_parser_relative:
* @url: a URI
* @output: a base path and filename
*
* Returns the URI of @url relative to @output if possible, and %NULL
* if not.
*
* <emphasis>See totem_pl_parser_resolve_url() to convert from relative URLs
* to absolute URLs.</emphasis>
*
* Return value: a newly-allocated relative URI string, or %NULL
**/
char *
totem_pl_parser_relative (const char *url, const char *output)
{
......@@ -688,6 +793,27 @@ totem_pl_parser_relative (const char *url, const char *output)
}
#ifndef TOTEM_PL_PARSER_MINI
/**
* totem_pl_parser_write_with_title:
* @parser: a #TotemPlParser
* @model: a #GtkTreeModel
* @func: a pointer to a #TotemPlParserIterFunc callback function
* @output: the output path and filename
* @title: the playlist title
* @type: a #TotemPlParserType for the ouputted playlist
* @user_data: a pointer to be passed to each call of @func
* @error: return location for a #GError, or %NULL
*
* Writes the playlist held by @parser and @model out to the file of
* path @output. The playlist is written in the format @type and is
* given the title @title.
*
* For each entry in the @model, the function @func is called (and passed
* @user_data), which gets various metadata values about the entry for
* the playlist writer.
*
* Return value: %TRUE on success
**/
gboolean
totem_pl_parser_write_with_title (TotemPlParser *parser, GtkTreeModel *model,
TotemPlParserIterFunc func,
......@@ -718,6 +844,26 @@ totem_pl_parser_write_with_title (TotemPlParser *parser, GtkTreeModel *model,
return FALSE;
}
/**
* totem_pl_parser_write:
* @parser: a #TotemPlParser
* @model: a #GtkTreeModel
* @func: a pointer to a #TotemPlParserIterFunc callback function
* @output: the output path and filename
* @type: a #TotemPlParserType for the ouputted playlist
* @user_data: a pointer to be passed to each call of @func
* @error: return location for a #GError, or %NULL
*
* Writes the playlist held by @parser and @model out to the file of
* path @output. The playlist is written in the format @type and is given
* a %NULL title.
*
* For each entry in the @model, the function @func is called (and passed
* @user_data), which gets various metadata values about the entry for
* the playlist writer.
*
* Return value: %TRUE on success
**/
gboolean
totem_pl_parser_write (TotemPlParser *parser, GtkTreeModel *model,
TotemPlParserIterFunc func,
......@@ -731,6 +877,16 @@ totem_pl_parser_write (TotemPlParser *parser, GtkTreeModel *model,
#endif /* TOTEM_PL_PARSER_MINI */
/**
* totem_pl_parser_read_ini_line_int:
* @lines: a NULL-terminated array of INI lines to read
* @key: the key to match
*
* Returns the first integer value case-insensitively matching the specified
* key as an integer. The parser ignores leading whitespace on lines.
*
* Return value: the integer value, or -1 on error
**/
int
totem_pl_parser_read_ini_line_int (char **lines, const char *key)
{
......@@ -763,6 +919,19 @@ totem_pl_parser_read_ini_line_int (char **lines, const char *key)
return retval;
}
/**
* totem_pl_parser_read_ini_line_string_with_sep:
* @lines: a NULL-terminated array of INI lines to read
* @key: the key to match
* @dos_mode: %TRUE if the returned string should end in \r\0, instead of \n\0
* @sep: the key-value separator
*
* Returns the first string value case-insensitively matching the specified
* key, where the two are separated by @sep. The parser ignores leading whitespace
* on lines.
*
* Return value: a newly-allocated string value, or %NULL
**/
char*
totem_pl_parser_read_ini_line_string_with_sep (char **lines, const char *key,
gboolean dos_mode, const char *sep)
......@@ -803,6 +972,17 @@ totem_pl_parser_read_ini_line_string_with_sep (char **lines, const char *key,
return retval;
}
/**
* totem_pl_parser_read_ini_line_string:
* @lines: a NULL-terminated array of INI lines to read
* @key: the key to match
* @dos_mode: %TRUE if the returned string should end in \r\0, instead of \n\0
*
* Returns the first string value case-insensitively matching the
* specified key. The parser ignores leading whitespace on lines.
*
* Return value: a newly-allocated string value, or %NULL
**/
char*
totem_pl_parser_read_ini_line_string (char **lines, const char *key, gboolean dos_mode)
{
......@@ -929,6 +1109,16 @@ totem_pl_parser_add_url_valist (TotemPlParser *parser,
g_object_unref (G_OBJECT (parser));
}
/**
* totem_pl_parser_add_url:
* @parser: a #TotemPlParser
* @first_property_name: the first property name
* @Varargs: value for the first property, followed optionally by more
* name/value pairs, followed by %NULL
*
* Adds a URL to the playlist with the properties given in @first_property_name
* and @Varargs.
**/
void
totem_pl_parser_add_url (TotemPlParser *parser,
const char *first_property_name,
......@@ -940,6 +1130,14 @@ totem_pl_parser_add_url (TotemPlParser *parser,
va_end (var_args);
}
/**
* totem_pl_parser_add_one_url:
* @parser: a #TotemPlParser
* @url: the entry's URL
* @title: the entry's title
*
* Adds a single URL entry with only URL and title strings to the playlist.
**/
void
totem_pl_parser_add_one_url (TotemPlParser *parser, const char *url, const char *title)
{
......@@ -977,6 +1175,19 @@ totem_pl_parser_might_be_file (const char *url)
return TRUE;
}
/**
* totem_pl_parser_resolve_url:
* @base: a base path and filename
* @url: a URI
*
* Returns the absolute URI of @url, resolving any relative
* paths with respect to @base.
*
* <emphasis>See totem_pl_parser_relative() to convert from absolute URLs
* to relative URLs.</emphasis>
*