GNOME.org
 

[brasero] More API documentation for BraseroBurnSession

commit 282346c08718f510646ef0d33410f4c4777cc7eb
Author: Philippe Rouquier <bonfire-app wanadoo fr>
Date:   Sat Aug 8 15:15:43 2009 +0200

    More API documentation for BraseroBurnSession

 libbrasero-burn/brasero-caps-session.c |  120 ++++++++++++++++++++++++++++++--
 libbrasero-burn/brasero-session.c      |   92 ++++++++++++++++++++++--
 libbrasero-burn/brasero-session.h      |   55 +++++++--------
 libbrasero-burn/brasero-track.c        |    3 +-
 4 files changed, 226 insertions(+), 44 deletions(-)
---
diff --git a/libbrasero-burn/brasero-caps-session.c b/libbrasero-burn/brasero-caps-session.c
index 099a399..d786f52 100644
--- a/libbrasero-burn/brasero-caps-session.c
+++ b/libbrasero-burn/brasero-caps-session.c
@@ -137,6 +137,23 @@ brasero_burn_caps_get_blanking_flags_real (BraseroBurnCaps *caps,
 	return BRASERO_BURN_OK;
 }
 
+/**
+ * brasero_burn_session_get_blank_flags:
+ * @session: a #BraseroBurnSession
+ * @supported: a #BraseroBurnFlag
+ * @compulsory: a #BraseroBurnFlag
+ *
+ * Given the various parameters stored in @session,
+ * stored in @supported and @compulsory, the flags
+ * that can be used (@supported) and must be used
+ * (@compulsory) when blanking the medium in the
+ * #BraseroDrive (set with brasero_burn_session_set_burner ()).
+ *
+ * Return value: a #BraseroBurnResult.
+ * BRASERO_BURN_OK if the retrieval was successful.
+ * BRASERO_BURN_ERR otherwise.
+ **/
+
 BraseroBurnResult
 brasero_burn_session_get_blank_flags (BraseroBurnSession *session,
 				      BraseroBurnFlag *supported,
@@ -232,6 +249,20 @@ brasero_burn_caps_can_blank_real (BraseroBurnCaps *self,
 	return BRASERO_BURN_NOT_SUPPORTED;
 }
 
+/**
+ * brasero_burn_session_can_blank:
+ * @session: a #BraseroBurnSession
+ *
+ * Given the various parameters stored in @session, this
+ * function checks whether the medium in the
+ * #BraseroDrive (set with brasero_burn_session_set_burner ())
+ * can be blanked.
+ *
+ * Return value: a #BraseroBurnResult.
+ * BRASERO_BURN_OK if it is possible.
+ * BRASERO_BURN_ERR otherwise.
+ **/
+
 BraseroBurnResult
 brasero_burn_session_can_blank (BraseroBurnSession *session)
 {
@@ -258,10 +289,6 @@ brasero_burn_session_can_blank (BraseroBurnSession *session)
 	return result;
 }
 
-/**
- *
- */
-
 static void
 brasero_caps_link_get_record_flags (BraseroCapsLink *link,
 				    BraseroMedia media,
@@ -602,6 +629,24 @@ brasero_caps_try_output_with_blanking (BraseroBurnCaps *self,
 				       io_flags);
 }
 
+/**
+ * brasero_burn_session_input_supported:
+ * @session: a #BraseroBurnSession
+ * @input: a #BraseroTrackType
+ * @use_flags: a #gboolean
+ *
+ * Given the various parameters stored in @session, this
+ * function checks whether a session with the data type
+ * @type could be burnt to the medium in the #BraseroDrive (set 
+ * through brasero_burn_session_set_burner ()).
+ * If @use_flags is TRUE, then flags are taken into account
+ * and are not if it is FALSE.
+ *
+ * Return value: a #BraseroBurnResult.
+ * BRASERO_BURN_OK if it is possible.
+ * BRASERO_BURN_ERR otherwise.
+ **/
+
 BraseroBurnResult
 brasero_burn_session_input_supported (BraseroBurnSession *session,
 				      BraseroTrackType *input,
@@ -667,7 +712,7 @@ brasero_burn_session_input_supported (BraseroBurnSession *session,
  * @output: a #BraseroTrackType *
  *
  * Make sure that the image type or medium type defined in @output can be
- * created/burnt given the parameters set in @session.
+ * created/burnt given the parameters and the current data set in @session.
  *
  * Return value: BRASERO_BURN_OK if the medium type or the image type can be used as an output.
  **/
@@ -841,6 +886,23 @@ brasero_burn_session_get_tmp_image_type_same_src_dest (BraseroBurnSession *sessi
 	return result;
 }
 
+/**
+ * brasero_burn_session_can_burn:
+ * @session: a #BraseroBurnSession
+ * @use_flags: a #gboolean
+ *
+ * Given the various parameters stored in @session, this
+ * function checks whether the data contained in @session
+ * can be burnt to the medium in the #BraseroDrive (set 
+ * through brasero_burn_session_set_burner ()).
+ * If @use_flags is set to TRUE the flags are taken into
+ * account, otherwise they are not.
+ *
+ * Return value: a #BraseroBurnResult.
+ * BRASERO_BURN_OK if it is possible.
+ * BRASERO_BURN_ERR otherwise.
+ **/
+
 BraseroBurnResult
 brasero_burn_session_can_burn (BraseroBurnSession *session,
 			       gboolean use_flags)
@@ -918,6 +980,16 @@ brasero_burn_session_can_burn (BraseroBurnSession *session,
 	return BRASERO_BURN_OK;
 }
 
+/**
+ * brasero_burn_session_get_required_media_type:
+ * @session: a #BraseroBurnSession
+ *
+ * Return the medium types that could be used to burn
+ * @session.
+ *
+ * Return value: a #BraseroMedia
+ **/
+
 BraseroMedia
 brasero_burn_session_get_required_media_type (BraseroBurnSession *session)
 {
@@ -991,6 +1063,17 @@ brasero_burn_session_get_required_media_type (BraseroBurnSession *session)
 	return required_media;
 }
 
+/**
+ * brasero_burn_session_get_possible_output_formats:
+ * @session: a #BraseroBurnSession
+ * @formats: a #BraseroImageFormat
+ *
+ * Returns the disc image types that could be set to create
+ * an image given the current state of @session.
+ *
+ * Return value: a #guint. The number of formats available.
+ **/
+
 guint
 brasero_burn_session_get_possible_output_formats (BraseroBurnSession *session,
 						  BraseroImageFormat *formats)
@@ -1024,6 +1107,16 @@ brasero_burn_session_get_possible_output_formats (BraseroBurnSession *session,
 	return num;
 }
 
+/**
+ * brasero_burn_session_get_default_output_format:
+ * @session: a #BraseroBurnSession
+ *
+ * Returns the default disc image type that should be set to create
+ * an image given the current state of @session.
+ *
+ * Return value: a #BraseroImageFormat
+ **/
+
 BraseroImageFormat
 brasero_burn_session_get_default_output_format (BraseroBurnSession *session)
 {
@@ -1545,6 +1638,23 @@ brasero_burn_caps_get_flags_same_src_dest (BraseroBurnCaps *self,
 	return BRASERO_BURN_OK;
 }
 
+/**
+ * brasero_burn_session_get_burn_flags:
+ * @session: a #BraseroBurnSession
+ * @supported: a #BraseroBurnFlag or NULL
+ * @compulsory: a #BraseroBurnFlag or NULL
+ *
+ * Given the various parameters stored in @session, this function
+ * stores:
+ * - the flags that can be used (@supported)
+ * - the flags that must be used (@compulsory)
+ * when writing @session to a disc.
+ *
+ * Return value: a #BraseroBurnResult.
+ * BRASERO_BURN_OK if the retrieval was successful.
+ * BRASERO_BURN_ERR otherwise.
+ **/
+
 BraseroBurnResult
 brasero_burn_session_get_burn_flags (BraseroBurnSession *session,
 				     BraseroBurnFlag *supported,
diff --git a/libbrasero-burn/brasero-session.c b/libbrasero-burn/brasero-session.c
index 3def39b..0a4e0d4 100644
--- a/libbrasero-burn/brasero-session.c
+++ b/libbrasero-burn/brasero-session.c
@@ -585,10 +585,6 @@ brasero_burn_session_get_input_type (BraseroBurnSession *self,
 	return BRASERO_BURN_OK;
 }
 
-/**
- *
- */
-
 static void
 brasero_burn_session_dest_media_added (BraseroDrive *drive,
 				       BraseroMedium *medium,
@@ -1490,6 +1486,19 @@ brasero_burn_session_tag_value_free (gpointer user_data)
 	g_free (value);
 }
 
+/**
+ * brasero_burn_session_tag_remove:
+ * @session: a #BraseroBurnSession
+ * @tag: a #gchar *
+ *
+ * Removes a value associated with @session through
+ * brasero_session_tag_add ().
+ *
+ * Return value: a #BraseroBurnResult.
+ * BRASERO_BURN_OK if the retrieval was successful
+ * BRASERO_BURN_ERR otherwise
+ **/
+
 BraseroBurnResult
 brasero_burn_session_tag_remove (BraseroBurnSession *self,
 				 const gchar *tag)
@@ -1506,6 +1515,22 @@ brasero_burn_session_tag_remove (BraseroBurnSession *self,
 	return BRASERO_BURN_OK;
 }
 
+/**
+ * brasero_burn_session_tag_add:
+ * @session: a #BraseroBurnSession
+ * @tag: a #gchar *
+ * @value: a #GValue *
+ *
+ * Associates a new @tag with @session. This can be used
+ * to pass arbitrary information for plugins, like parameters
+ * for video discs, ...
+ * See brasero-tags.h for a list of knowns tags.
+ *
+ * Return value: a #BraseroBurnResult.
+ * BRASERO_BURN_OK if it was successful,
+ * BRASERO_BURN_ERR otherwise.
+ **/
+
 BraseroBurnResult
 brasero_burn_session_tag_add (BraseroBurnSession *self,
 			      const gchar *tag,
@@ -1525,6 +1550,21 @@ brasero_burn_session_tag_add (BraseroBurnSession *self,
 	return BRASERO_BURN_OK;
 }
 
+/**
+ * brasero_burn_session_tag_lookup:
+ * @session: a #BraseroBurnSession
+ * @tag: a #gchar *
+ * @value: a #GValue
+ *
+ * Retrieves a value associated with @session through
+ * brasero_session_tag_add () and stores it in @value. Do
+ * not destroy @value afterwards as it is not a copy.
+ *
+ * Return value: a #BraseroBurnResult.
+ * BRASERO_BURN_OK if the retrieval was successful
+ * BRASERO_BURN_ERR otherwise
+ **/
+
 BraseroBurnResult
 brasero_burn_session_tag_lookup (BraseroBurnSession *self,
 				 const gchar *tag,
@@ -1690,10 +1730,6 @@ brasero_burn_session_pop_tracks (BraseroBurnSession *self)
 	return BRASERO_BURN_RETRY;
 }
 
-/**
- *
- */
-
 gboolean
 brasero_burn_session_is_dest_file (BraseroBurnSession *self)
 {
@@ -2142,6 +2178,14 @@ brasero_burn_session_class_init (BraseroBurnSessionClass *klass)
 	klass->set_output_image = brasero_burn_session_set_output_image_real;
 
 	/* This is to delay the setting of track source until we know all settings */
+	/**
+ 	* BraseroBurnSession::output-changed:
+ 	* @session: the object which received the signal
+  	* @former_medium: the medium which was previously set
+	*
+ 	* This signal gets emitted when the medium to burn to changed.
+ 	*
+ 	*/
 	brasero_burn_session_signals [OUTPUT_CHANGED_SIGNAL] =
 	    g_signal_new ("output_changed",
 			  BRASERO_TYPE_BURN_SESSION,
@@ -2153,6 +2197,14 @@ brasero_burn_session_class_init (BraseroBurnSessionClass *klass)
 			  G_TYPE_NONE,
 			  1,
 			  BRASERO_TYPE_MEDIUM);
+	/**
+ 	* BraseroBurnSession::track-added:
+ 	* @session: the object which received the signal
+  	* @track: the track that was added
+	*
+ 	* This signal gets emitted when a track is added to @session.
+ 	*
+ 	*/
 	brasero_burn_session_signals [TRACK_ADDED_SIGNAL] =
 	    g_signal_new ("track_added",
 			  BRASERO_TYPE_BURN_SESSION,
@@ -2164,6 +2216,15 @@ brasero_burn_session_class_init (BraseroBurnSessionClass *klass)
 			  G_TYPE_NONE,
 			  1,
 			  BRASERO_TYPE_TRACK);
+	/**
+ 	* BraseroBurnSession::track-removed:
+ 	* @session: the object which received the signal
+  	* @track: the track that was removed
+	* @former_position: the former position of @track
+	*
+ 	* This signal gets emitted when a track is removed from @session.
+ 	*
+ 	*/
 	brasero_burn_session_signals [TRACK_REMOVED_SIGNAL] =
 	    g_signal_new ("track_removed",
 			  BRASERO_TYPE_BURN_SESSION,
@@ -2176,6 +2237,14 @@ brasero_burn_session_class_init (BraseroBurnSessionClass *klass)
 			  2,
 			  BRASERO_TYPE_TRACK,
 			  G_TYPE_UINT);
+	/**
+ 	* BraseroBurnSession::track-changed:
+ 	* @session: the object which received the signal
+  	* @track: the track that changed
+	*
+ 	* This signal gets emitted when the contents of a track changed.
+ 	*
+ 	*/
 	brasero_burn_session_signals [TRACK_CHANGED_SIGNAL] =
 	    g_signal_new ("track_changed",
 			  BRASERO_TYPE_BURN_SESSION,
@@ -2187,6 +2256,13 @@ brasero_burn_session_class_init (BraseroBurnSessionClass *klass)
 			  G_TYPE_NONE,
 			  1,
 			  BRASERO_TYPE_TRACK);
+	/**
+ 	* BraseroBurnSession::flags-changed:
+ 	* @session: the object which received the signal
+	*
+ 	* This signal gets emitted when the flags changed for @session.
+ 	*
+ 	*/
 	brasero_burn_session_signals [FLAGS_CHANGED_SIGNAL] =
 	    g_signal_new ("flags_changed",
 			  BRASERO_TYPE_BURN_SESSION,
diff --git a/libbrasero-burn/brasero-session.h b/libbrasero-burn/brasero-session.h
index 452d789..7a4e98e 100644
--- a/libbrasero-burn/brasero-session.h
+++ b/libbrasero-burn/brasero-session.h
@@ -70,12 +70,6 @@ struct _BraseroBurnSessionClass {
 							 gchar **toc);
 	BraseroImageFormat	(*get_output_format)	(BraseroBurnSession *session);
 
-	/**
-	 * GObject signals could be used to warned of individual property
-	 * changes but since changing one property could change others
-	 * it's better to have one global signal and dialogs asking for
-	 * the session properties they are interested in.
-	 */
 	void			(*flags_changed)	(BraseroBurnSession *session);
 	void			(*track_added)		(BraseroBurnSession *session,
 							 BraseroTrack *track);
@@ -175,6 +169,20 @@ BraseroImageFormat
 brasero_burn_session_get_output_format (BraseroBurnSession *session);
 
 
+const gchar *
+brasero_burn_session_get_label (BraseroBurnSession *session);
+
+void
+brasero_burn_session_set_label (BraseroBurnSession *session,
+				const gchar *label);
+
+BraseroBurnResult
+brasero_burn_session_set_rate (BraseroBurnSession *session,
+			       guint64 rate);
+
+guint64
+brasero_burn_session_get_rate (BraseroBurnSession *session);
+
 /**
  * Session flags
  */
@@ -206,21 +214,6 @@ const gchar *
 brasero_burn_session_get_tmpdir (BraseroBurnSession *session);
 
 /**
- * Allow to save a whole session settings/source and restore it later.
- * (mostly used internally)
- */
-
-void
-brasero_burn_session_push_settings (BraseroBurnSession *session);
-void
-brasero_burn_session_pop_settings (BraseroBurnSession *session);
-
-void
-brasero_burn_session_push_tracks (BraseroBurnSession *session);
-BraseroBurnResult
-brasero_burn_session_pop_tracks (BraseroBurnSession *session);
-
-/**
  * Test the supported or compulsory flags for a given session
  */
 
@@ -266,6 +259,7 @@ brasero_burn_session_get_default_output_format (BraseroBurnSession *session);
 
 /**
  * This is to log a session
+ * (used internally)
  */
 
 const gchar *
@@ -289,20 +283,21 @@ brasero_burn_session_log (BraseroBurnSession *session,
 			  const gchar *format,
 			  ...);
 
-
-const gchar *
-brasero_burn_session_get_label (BraseroBurnSession *session);
+/**
+ * Allow to save a whole session settings/source and restore it later.
+ * (used internally)
+ */
 
 void
-brasero_burn_session_set_label (BraseroBurnSession *session,
-				const gchar *label);
+brasero_burn_session_push_settings (BraseroBurnSession *session);
+void
+brasero_burn_session_pop_settings (BraseroBurnSession *session);
 
+void
+brasero_burn_session_push_tracks (BraseroBurnSession *session);
 BraseroBurnResult
-brasero_burn_session_set_rate (BraseroBurnSession *session,
-			       guint64 rate);
+brasero_burn_session_pop_tracks (BraseroBurnSession *session);
 
-guint64
-brasero_burn_session_get_rate (BraseroBurnSession *session);
 
 G_END_DECLS
 
diff --git a/libbrasero-burn/brasero-track.c b/libbrasero-burn/brasero-track.c
index f1bb4e4..74da677 100644
--- a/libbrasero-burn/brasero-track.c
+++ b/libbrasero-burn/brasero-track.c
@@ -251,6 +251,7 @@ brasero_track_get_checksum_type (BraseroTrack *track)
 /**
  * Can be used to set arbitrary data
  */
+
 static void
 brasero_track_tag_value_free (gpointer user_data)
 {
@@ -267,7 +268,7 @@ brasero_track_tag_value_free (gpointer user_data)
  * @value: a #GValue
  *
  * Associates a new @tag with a track. This can be used
- * to pass arbitrary information for plugin, like parameters
+ * to pass arbitrary information for plugins, like parameters
  * for video discs, ...
  * See brasero-tags.h for a list of knowns tags.
  *
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]