totem-pl-parser r256 - in trunk: . plparse

[pwithnall svn gnome org]

Author: pwithnall
Date: Thu Nov 27 17:18:39 2008
New Revision: 256
URL: http://svn.gnome.org/viewvc/totem-pl-parser?rev=256&view=rev

Log:
2008-11-27  Philip Withnall  <philip tecnocode co uk>

	* plparse/totem-disc.c (cd_cache_new), (cd_cache_open_device),
	(cd_cache_open_mountpoint):
	* plparse/totem-pl-parser.c:
	* plparse/totem-pl-parser.h: Expand API documentation re. error 
codes;
	fix g_set_error calls with 0 domain/code; and mention functions 
which
	do sync I/O. (Closes: #560495, #560493, #560491)



Modified:
   trunk/ChangeLog
   trunk/plparse/totem-disc.c
   trunk/plparse/totem-pl-parser.c
   trunk/plparse/totem-pl-parser.h

Modified: trunk/plparse/totem-disc.c
==============================================================================
--- trunk/plparse/totem-disc.c	(original)
+++ trunk/plparse/totem-disc.c	Thu Nov 27 17:18:39 2008
@@ -315,8 +315,8 @@
 	if (data.error) {
 	  g_propagate_error (error, data.error);
 	} else {
-	  g_set_error (error, 0, 0,
-		       _("Failed to mount %s"), cache->device);
+	  g_set_error (error, TOTEM_PL_PARSER_ERROR, TOTEM_PL_PARSER_ERROR_MOUNT_FAILED,
+		       _("Failed to mount %s."), cache->device);
 	}
 	cd_cache_free (cache);
 	return FALSE;
@@ -345,8 +345,8 @@
   mon = g_volume_monitor_get ();
   found = cd_cache_get_dev_from_volumes (mon, device, &mountpoint, &volume);
   if (!found) {
-    g_set_error (error, 0, 0,
-	_("No media in drive for device '%s'"),
+    g_set_error (error, TOTEM_PL_PARSER_ERROR, TOTEM_PL_PARSER_ERROR_NO_DISC,
+	_("No media in drive for device '%s'."),
 	device);
     g_free (device);
     return NULL;
@@ -399,7 +399,7 @@
   }
 
   if (cd_cache_has_medium (cache) == FALSE) {
-    g_set_error (error, 0, 0,
+    g_set_error (error, TOTEM_PL_PARSER_ERROR, TOTEM_PL_PARSER_ERROR_NO_DISC,
 	_("Please check that a disc is present in the drive."));
     return FALSE;
   }
@@ -456,8 +456,8 @@
       if (data.error) {
 	g_propagate_error (error, data.error);
       } else {
-	g_set_error (error, 0, 0,
-		     _("Failed to mount %s"), cache->device);
+	g_set_error (error, TOTEM_PL_PARSER_ERROR, TOTEM_PL_PARSER_ERROR_MOUNT_FAILED,
+		     _("Failed to mount %s."), cache->device);
       }
       return FALSE;
     } else {
@@ -628,6 +628,14 @@
  * a string pointer is passed to @url, it will return the disc's
  * MRL as from totem_cd_mrl_from_type().
  *
+ * Note that this function does synchronous I/O.
+ *
+ * If no disc is present in the drive, a #TOTEM_PL_PARSER_ERROR_NO_DISC
+ * error will be returned. On unknown mounting errors, a
+ * #TOTEM_PL_PARSER_ERROR_MOUNT_FAILED error will be returned. On other
+ * I/O errors, or if resolution of symlinked mount paths failed, a code from
+ * #GIOErrorEnum will be returned.
+ *
  * Return value: #TotemDiscMediaType corresponding to the disc's type, or #MEDIA_TYPE_ERROR on failure
  **/
 TotemDiscMediaType
@@ -688,6 +696,10 @@
  * a string pointer is passed to @url, it will return the disc's
  * MRL as from totem_cd_mrl_from_type().
  *
+ * Note that this function does synchronous I/O.
+ *
+ * Possible error codes are as per totem_cd_detect_type_from_dir().
+ *
  * Return value: #TotemDiscMediaType corresponding to the disc's type, or #MEDIA_TYPE_ERROR on failure
  **/
 TotemDiscMediaType
@@ -779,6 +791,8 @@
  *
  * Detects the disc's type, given its device node path.
  *
+ * Possible error codes are as per totem_cd_detect_type_with_url().
+ *
  * Return value: #TotemDiscMediaType corresponding to the disc's type, or #MEDIA_TYPE_ERROR on failure
  **/
 TotemDiscMediaType

Modified: trunk/plparse/totem-pl-parser.c
==============================================================================
--- trunk/plparse/totem-pl-parser.c	(original)
+++ trunk/plparse/totem-pl-parser.c	Thu Nov 27 17:18:39 2008
@@ -750,6 +750,7 @@
  * @error: return location for a #GError, or %NULL
  *
  * Writes the string @buf out to the file specified by @handle.
+ * Possible error codes are as per totem_pl_parser_write_buffer().
  *
  * Return value: %TRUE on success
  **/
@@ -771,6 +772,8 @@
  *
  * Writes @len bytes of @buf to the file specified by @handle.
  *
+ * A value of @len greater than #G_MAXSSIZE will cause a #G_IO_ERROR_INVALID_ARGUMENT argument.
+ *
  * Return value: %TRUE on success
  **/
 gboolean
@@ -870,6 +873,20 @@
  * @user_data), which gets various metadata values about the entry for
  * the playlist writer.
  *
+ * If the @output file is a directory the #G_IO_ERROR_IS_DIRECTORY error
+ * will be returned, and if the file is some other form of non-regular file
+ * then a #G_IO_ERROR_NOT_REGULAR_FILE error will be returned. Some file
+ * systems don't allow all file names, and may return a
+ * #G_IO_ERROR_INVALID_FILENAME error, and if the name is too long,
+ * #G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are possible
+ * too, and depend on what kind of filesystem the file is on.
+ *
+ * In extreme cases, a #G_IO_ERROR_INVALID_ARGUMENT error can be returned, if
+ * parts of the playlist to be written are too long.
+ *
+ * If writing a PLA playlist and there is an error converting a URI's encoding,
+ * a code from #GConvertError will be returned.
+ *
  * Return value: %TRUE on success
  **/
 gboolean
@@ -926,6 +943,8 @@
  * @user_data), which gets various metadata values about the entry for
  * the playlist writer.
  *
+ * Possible error codes are as per totem_pl_parser_write_with_title().
+ *
  * Return value: %TRUE on success
  **/
 gboolean

Modified: trunk/plparse/totem-pl-parser.h
==============================================================================
--- trunk/plparse/totem-pl-parser.h	(original)
+++ trunk/plparse/totem-pl-parser.h	Thu Nov 27 17:18:39 2008
@@ -288,6 +288,8 @@
  * TotemPlParserError:
  * @TOTEM_PL_PARSER_ERROR_VFS_OPEN: Error on opening a file
  * @TOTEM_PL_PARSER_ERROR_VFS_WRITE: Error on writing a file
+ * @TOTEM_PL_PARSER_ERROR_NO_DISC: Error attempting to open a disc device when no disc is present
+ * @TOTEM_PL_PARSER_ERROR_MOUNT_FAILED: An attempted mount operation failed
  *
  * Allows you to differentiate between different
  * errors occurring during file operations in a #TotemPlParser.
@@ -296,6 +298,8 @@
 {
 	TOTEM_PL_PARSER_ERROR_VFS_OPEN,
 	TOTEM_PL_PARSER_ERROR_VFS_WRITE,
+	TOTEM_PL_PARSER_ERROR_NO_DISC,
+	TOTEM_PL_PARSER_ERROR_MOUNT_FAILED
 } TotemPlParserError;
 
 #define TOTEM_PL_PARSER_ERROR (totem_pl_parser_error_quark ())