BraseroBurnSession

## BraseroBurnSession BraseroBurnSession — Store parameters when burning and blanking |

## Synopsis

    #include <brasero-session.h>

                        BraseroBurnSession;
                        BraseroBurnSessionClass;
    BraseroBurnSession * brasero_burn_session_new           (void);
    BraseroBurnResult   brasero_burn_session_add_track      (BraseroBurnSession *session,
                                                             BraseroTrack *new_track,
                                                             BraseroTrack *sibling);
    BraseroBurnResult   brasero_burn_session_move_track     (BraseroBurnSession *session,
                                                             BraseroTrack *track,
                                                             BraseroTrack *sibling);
    BraseroBurnResult   brasero_burn_session_remove_track   (BraseroBurnSession *session,
                                                             BraseroTrack *track);
    GSList *            brasero_burn_session_get_tracks     (BraseroBurnSession *session);
    BraseroBurnResult   brasero_burn_session_get_status     (BraseroBurnSession *session,
                                                             BraseroStatus *status);
    BraseroBurnResult   brasero_burn_session_get_size       (BraseroBurnSession *session,
                                                             goffset *blocks,
                                                             goffset *bytes);
    BraseroBurnResult   brasero_burn_session_get_input_type (BraseroBurnSession *session,
                                                             BraseroTrackType *type);
    BraseroBurnResult   brasero_burn_session_tag_lookup     (BraseroBurnSession *session,
                                                             const gchar *tag,
                                                             GValue **value);
    BraseroBurnResult   brasero_burn_session_tag_add        (BraseroBurnSession *session,
                                                             const gchar *tag,
                                                             GValue *value);
    BraseroBurnResult   brasero_burn_session_tag_remove     (BraseroBurnSession *session,
                                                             const gchar *tag);
    BraseroDrive *      brasero_burn_session_get_burner     (BraseroBurnSession *session);
    void                brasero_burn_session_set_burner     (BraseroBurnSession *session,
                                                             BraseroDrive *drive);
    BraseroBurnResult   brasero_burn_session_set_image_output_full
                                                            (BraseroBurnSession *session,
                                                             BraseroImageFormat format,
                                                             const gchar *image,
                                                             const gchar *toc);
    BraseroBurnResult   brasero_burn_session_get_output     (BraseroBurnSession *session,
                                                             gchar **image,
                                                             gchar **toc);
    BraseroImageFormat  brasero_burn_session_get_output_format
                                                            (BraseroBurnSession *session);
    void                brasero_burn_session_set_flags      (BraseroBurnSession *session,
                                                             BraseroBurnFlag flags);
    void                brasero_burn_session_add_flag       (BraseroBurnSession *session,
                                                             BraseroBurnFlag flags);
    void                brasero_burn_session_remove_flag    (BraseroBurnSession *session,
                                                             BraseroBurnFlag flags);
    BraseroBurnFlag     brasero_burn_session_get_flags      (BraseroBurnSession *session);
    BraseroBurnResult   brasero_burn_session_set_tmpdir     (BraseroBurnSession *session,
                                                             const gchar *path);
    const gchar *       brasero_burn_session_get_tmpdir     (BraseroBurnSession *session);
    BraseroBurnResult   brasero_burn_session_get_burn_flags (BraseroBurnSession *session,
                                                             BraseroBurnFlag *supported,
                                                             BraseroBurnFlag *compulsory);
    BraseroBurnResult   brasero_burn_session_get_blank_flags
                                                            (BraseroBurnSession *session,
                                                             BraseroBurnFlag *supported,
                                                             BraseroBurnFlag *compulsory);
    BraseroBurnResult   brasero_burn_session_can_blank      (BraseroBurnSession *session);
    BraseroBurnResult   brasero_burn_session_can_burn       (BraseroBurnSession *session,
                                                             gboolean check_flags);
    BraseroBurnResult   brasero_burn_session_input_supported
                                                            (BraseroBurnSession *session,
                                                             BraseroTrackType *input,
                                                             gboolean check_flags);
    BraseroBurnResult   brasero_burn_session_output_supported
                                                            (BraseroBurnSession *session,
                                                             BraseroTrackType *output);
    BraseroMedia        brasero_burn_session_get_required_media_type
                                                            (BraseroBurnSession *session);
    guint               brasero_burn_session_get_possible_output_formats
                                                            (BraseroBurnSession *session,
                                                             BraseroImageFormat *formats);
    BraseroImageFormat  brasero_burn_session_get_default_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);

## Description

This object stores all parameters for all operations performed by BraseroBurn such as burning, blanking and checksuming. To have this object configured automatically see BraseroSessionCfg.

## Details

### BraseroBurnSession

    typedef struct {
    	GObject parent;
    } BraseroBurnSession;

### BraseroBurnSessionClass

    typedef struct {
    	GObjectClass parent_class;

    	/** Virtual functions **/
    	BraseroBurnResult (*set_output_image) (BraseroBurnSession *session,
    							 BraseroImageFormat format,
    							 const gchar *image,
    							 const gchar *toc);
    	BraseroBurnResult (*get_output_path) (BraseroBurnSession *session,
    							 gchar **image,
    							 gchar **toc);
    	BraseroImageFormat (*get_output_format) (BraseroBurnSession *session);

    	/** Signals **/
    	void			(*tag_changed)		(BraseroBurnSession *session,
    					                 const gchar *tag);
    	void			(*track_added)		(BraseroBurnSession *session,
    							 BraseroTrack *track);
    	void			(*track_removed) (BraseroBurnSession *session,
    							 BraseroTrack *track,
    							 guint former_position);
    	void			(*track_changed) (BraseroBurnSession *session,
    							 BraseroTrack *track);
    	void			(*output_changed) (BraseroBurnSession *session,
    							 BraseroMedium *former_medium);
    } BraseroBurnSessionClass;

### brasero_burn_session_new ()

    BraseroBurnSession * brasero_burn_session_new           (void);

Returns a new BraseroBurnSession object.

Returns : | a BraseroBurnSession.

### brasero_burn_session_add_track ()

    BraseroBurnResult   brasero_burn_session_add_track      (BraseroBurnSession *session,
                                                             BraseroTrack *new_track,
                                                             BraseroTrack *sibling);

Inserts a new track after `sibling` or appended if `sibling` is NULL. If `track` is NULL then all tracks already in `session` will be removed. NOTE: if there are already BraseroTrack objects inserted in the session and if they are not of the same type as `new_track` then they will be removed before the insertion of `new_track`.

`session` : | a BraseroBurnSession.
`new_track` : | a BraseroTrack or NULL. [allow-none]
`sibling` : | a BraseroTrack or NULL. [allow-none]
Returns : | a BraseroBurnResult. BRASERO_BURN_OK if the track was successfully inserted or BRASERO_BURN_ERR otherwise.

### brasero_burn_session_move_track ()

    BraseroBurnResult   brasero_burn_session_move_track     (BraseroBurnSession *session,
                                                             BraseroTrack *track,
                                                             BraseroTrack *sibling);

Moves `track` after `sibling`; if `sibling` is NULL then it is appended.

`session` : | a BraseroBurnSession.
`track` : | a BraseroTrack.
`sibling` : | a BraseroTrack or NULL. [allow-none]
Returns : | a BraseroBurnResult. BRASERO_BURN_OK if the track was successfully moved or BRASERO_BURN_ERR otherwise.

### brasero_burn_session_remove_track ()

    BraseroBurnResult   brasero_burn_session_remove_track   (BraseroBurnSession *session,
                                                             BraseroTrack *track);

Removes `track` from `session`.

`session` : | a BraseroBurnSession
`track` : | a BraseroTrack
Returns : | a BraseroBurnResult. BRASERO_BURN_OK if the track was successfully removed or BRASERO_BURN_ERR otherwise.

### brasero_burn_session_get_tracks ()

    GSList *            brasero_burn_session_get_tracks     (BraseroBurnSession *session);

Returns the list of BraseroTrack added to `session`.

`session` : | a BraseroBurnSession
Returns : | a GSList or BraseroTrack object. Do not unref the objects in the list nor destroy the list. [element-type BraseroBurn.Track][transfer none BraseroBurn.Track]

### brasero_burn_session_get_status ()

    BraseroBurnResult   brasero_burn_session_get_status     (BraseroBurnSession *session,
                                                             BraseroStatus *status);

Sets `status` to reflect whether `session` is ready to be used.

`session` : | a BraseroBurnSession
`status` : | a BraseroTrackStatus
Returns : | a BraseroBurnResult. BRASERO_BURN_OK if it was successful BRASERO_BURN_NOT_READY if `track` needs more time for processing BRASERO_BURN_ERR if something is wrong or if it is empty

### brasero_burn_session_get_size ()

    BraseroBurnResult   brasero_burn_session_get_size       (BraseroBurnSession *session,
                                                             goffset *blocks,
                                                             goffset *bytes);

Returns the size of the data contained by `session` in bytes or in sectors

`session` : | a BraseroBurnSession
`blocks` : | a goffset or NULL
`bytes` : | a goffset or NULL
Returns : | a BraseroBurnResult. BRASERO_BURN_OK if it was successful BRASERO_BURN_NOT_READY if `track` needs more time for processing the size BRASERO_BURN_ERR if something is wrong or if it is empty

### brasero_burn_session_get_input_type ()

    BraseroBurnResult   brasero_burn_session_get_input_type (BraseroBurnSession *session,
                                                             BraseroTrackType *type);

Sets `type` to reflect the type of data contained in `session`

`session` : | a BraseroBurnSession
`type` : | a BraseroTrackType or NULL
Returns : | a BraseroBurnResult. BRASERO_BURN_OK if it was successful

### brasero_burn_session_tag_lookup ()

    BraseroBurnResult   brasero_burn_session_tag_lookup     (BraseroBurnSession *session,
                                                             const gchar *tag,
                                                             GValue **value);

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.

`session` : | a BraseroBurnSession
`tag` : | a gchar *
`value` : | a GValue
Returns : | a BraseroBurnResult. BRASERO_BURN_OK if the retrieval was successful BRASERO_BURN_ERR otherwise

### brasero_burn_session_tag_add ()

    BraseroBurnResult   brasero_burn_session_tag_add        (BraseroBurnSession *session,
                                                             const gchar *tag,
                                                             GValue *value);

Associates a new `tag` with `session`. This can be used to pass arbitrary information for plugins, like parameters for video discs, ... NOTE: the BraseroBurnSession object takes ownership of `value`. See brasero-tags.h for a list of knowns tags.

`session` : | a BraseroBurnSession
`tag` : | a gchar *
`value` : | a GValue *
Returns : | a BraseroBurnResult. BRASERO_BURN_OK if it was successful, BRASERO_BURN_ERR otherwise.

### brasero_burn_session_tag_remove ()

    BraseroBurnResult   brasero_burn_session_tag_remove     (BraseroBurnSession *session,
                                                             const gchar *tag);

Removes a value associated with `session` through `brasero_session_tag_add()`.

`session` : | a BraseroBurnSession
`tag` : | a gchar *
Returns : | a BraseroBurnResult. BRASERO_BURN_OK if the retrieval was successful BRASERO_BURN_ERR otherwise

### brasero_burn_session_get_burner ()

    BraseroDrive *      brasero_burn_session_get_burner     (BraseroBurnSession *session);

Returns the BraseroDrive that should be used to burn the session contents.

`session` : | a BraseroBurnSession
Returns : | a BraseroDrive or NULL. Do not unref after use. [transfer none][allow-none]

### brasero_burn_session_set_burner ()

    void                brasero_burn_session_set_burner     (BraseroBurnSession *session,
                                                             BraseroDrive *drive);

Sets the BraseroDrive that should be used to burn the session contents.

`session` : | a BraseroBurnSession
`drive` : | a BraseroDrive

### brasero_burn_session_set_image_output_full ()

    BraseroBurnResult   brasero_burn_session_set_image_output_full
                                                            (BraseroBurnSession *session,
                                                             BraseroImageFormat format,
                                                             const gchar *image,
                                                             const gchar *toc);

When the contents of `session` should be written to a file, this function sets the different parameters of this image like its path (and the one of the associated toc if necessary) and its format.

NOTE: after a call to this function the BraseroDrive for `session` will be the fake BraseroDrive.

`session` : | a BraseroBurnSession.
`format` : | a BraseroImageFormat.
`image` : | a gchar or NULL. [allow-none]
`toc` : | a gchar or NULL. [allow-none]
Returns : | a BraseroBurnResult. BRASERO_BURN_OK if it was successfully set; BRASERO_BURN_ERR otherwise.

### brasero_burn_session_get_output ()

    BraseroBurnResult   brasero_burn_session_get_output     (BraseroBurnSession *session,
                                                             gchar **image,
                                                             gchar **toc);

When the contents of `session` should be written to a file then this function returns the image path (and if necessary a toc path). `image` and `toc` should be freed if not used anymore.

NOTE: before using this function a BraseroDrive should have been set with `brasero_burn_session_set_burner()` and it should be the fake drive (see `brasero_drive_is_fake()`).

`session` : | a BraseroBurnSession.
`image` : | a gchar to store the image path or NULL. [allow-none][out]
`toc` : | a gchar to store the toc path or NULL. [allow-none][out]
Returns : | a BraseroBurnResult. BRASERO_BURN_OK if it was successful; BRASERO_BURN_ERR otherwise.

### brasero_burn_session_get_output_format ()

    BraseroImageFormat  brasero_burn_session_get_output_format
                                                            (BraseroBurnSession *session);

When the contents of `session` should be written to a file then this function returns the format of the image to write.

NOTE: before using this function a BraseroDrive should have been set with `brasero_burn_session_set_burner()` and it should be the fake drive (see `brasero_drive_is_fake()`).

`session` : | a BraseroBurnSession
Returns : | a BraseroImageFormat. The format of the image to be written.

### brasero_burn_session_set_flags ()

    void                brasero_burn_session_set_flags      (BraseroBurnSession *session,
                                                             BraseroBurnFlag flags);

Replaces the current flags set in `session` with `flags`.

`session` : | a BraseroBurnSession
`flags` : | a BraseroBurnFlag

### brasero_burn_session_add_flag ()

    void                brasero_burn_session_add_flag       (BraseroBurnSession *session,
                                                             BraseroBurnFlag flags);

Merges the current flags set in `session` with `flags`.

`session` : | a BraseroBurnSession
`flags` : | a BraseroBurnFlag

### brasero_burn_session_remove_flag ()

    void                brasero_burn_session_remove_flag    (BraseroBurnSession *session,
                                                             BraseroBurnFlag flags);

Removes `flags` from the current flags set for `session`.

`session` : | a BraseroBurnSession
`flags` : | a BraseroBurnFlag

### brasero_burn_session_get_flags ()

    BraseroBurnFlag     brasero_burn_session_get_flags      (BraseroBurnSession *session);

Returns the current flags set for `session`.

`session` : | a BraseroBurnSession
Returns : | a BraseroBurnFlag.

### brasero_burn_session_set_tmpdir ()

    BraseroBurnResult   brasero_burn_session_set_tmpdir     (BraseroBurnSession *session,
                                                             const gchar *path);

Sets the path of the directory in which to write temporary directories and files. If set to NULL then the result of `g_get_tmp_dir()` will be used.

`session` : | a BraseroBurnSession
`path` : | a gchar or NULL
Returns : | a BraseroBurnResult. BRASERO_BURN_OK if it was successfully set; BRASERO_BURN_ERR otherwise.

### brasero_burn_session_get_tmpdir ()

    const gchar *       brasero_burn_session_get_tmpdir     (BraseroBurnSession *session);

Returns the path of the directory in which to write temporary directories and files.

`session` : | a BraseroBurnSession
Returns : | a gchar. The path to the temporary directory.

### brasero_burn_session_get_burn_flags ()

    BraseroBurnResult   brasero_burn_session_get_burn_flags (BraseroBurnSession *session,
                                                             BraseroBurnFlag *supported,
                                                             BraseroBurnFlag *compulsory);

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.

`session` : | a BraseroBurnSession
`supported` : | a BraseroBurnFlag or NULL
`compulsory` : | a BraseroBurnFlag or NULL
Returns : | a BraseroBurnResult. BRASERO_BURN_OK if the retrieval was successful. BRASERO_BURN_ERR otherwise.

### brasero_burn_session_get_blank_flags ()

    BraseroBurnResult   brasero_burn_session_get_blank_flags
                                                            (BraseroBurnSession *session,
                                                             BraseroBurnFlag *supported,
                                                             BraseroBurnFlag *compulsory);

Given the various parameters stored in `session`, stores 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()`).

`session` : | a BraseroBurnSession
`supported` : | a BraseroBurnFlag
`compulsory` : | a BraseroBurnFlag
Returns : | a BraseroBurnResult. BRASERO_BURN_OK if the retrieval was successful. BRASERO_BURN_ERR otherwise.

### brasero_burn_session_can_blank ()

    BraseroBurnResult   brasero_burn_session_can_blank      (BraseroBurnSession *session);

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.

`session` : | a BraseroBurnSession
Returns : | a BraseroBurnResult. BRASERO_BURN_OK if it is possible. BRASERO_BURN_ERR otherwise.

### brasero_burn_session_can_burn ()

    BraseroBurnResult   brasero_burn_session_can_burn       (BraseroBurnSession *session,
                                                             gboolean check_flags);

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 `check_flags` determine the behavior of this function.

`session` : | a BraseroBurnSession
`check_flags` : | a gboolean
Returns : | a BraseroBurnResult. BRASERO_BURN_OK if it is possible. BRASERO_BURN_ERR otherwise.

### brasero_burn_session_input_supported ()

    BraseroBurnResult   brasero_burn_session_input_supported
                                                            (BraseroBurnSession *session,
                                                             BraseroTrackType *input,
                                                             gboolean check_flags);

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 `check_flags` is `TRUE`, then flags are taken into account and are not if it is `FALSE`.

`session` : | a BraseroBurnSession
`input` : | a BraseroTrackType
`check_flags` : | a gboolean
Returns : | a BraseroBurnResult. BRASERO_BURN_OK if it is possible. BRASERO_BURN_ERR otherwise.

### brasero_burn_session_output_supported ()

    BraseroBurnResult   brasero_burn_session_output_supported
                                                            (BraseroBurnSession *session,
                                                             BraseroTrackType *output);

Make sure that the image type or medium type defined in `output` can be created/burnt given the parameters and the current data set in `session`.

`session` : | a BraseroBurnSession *
`output` : | a BraseroTrackType *
Returns : | BRASERO_BURN_OK if the medium type or the image type can be used as an output.

### brasero_burn_session_get_required_media_type ()

    BraseroMedia        brasero_burn_session_get_required_media_type
                                                            (BraseroBurnSession *session);

Return the medium types that could be used to burn `session`.

`session` : | a BraseroBurnSession
Returns : | a BraseroMedia

### brasero_burn_session_get_possible_output_formats ()

    guint               brasero_burn_session_get_possible_output_formats
                                                            (BraseroBurnSession *session,
                                                             BraseroImageFormat *formats);

Returns the disc image types that could be set to create an image given the current state of `session`.

`session` : | a BraseroBurnSession
`formats` : | a BraseroImageFormat
Returns : | a guint. The number of formats available.

### brasero_burn_session_get_default_output_format ()

    BraseroImageFormat  brasero_burn_session_get_default_output_format
                                                            (BraseroBurnSession *session);

Returns the default disc image type that should be set to create an image given the current state of `session`.

`session` : | a BraseroBurnSession
Returns : | a BraseroImageFormat

### brasero_burn_session_get_label ()

    const gchar *       brasero_burn_session_get_label      (BraseroBurnSession *session);

Returns the label (a string) set for `session`.

`session` : | a BraseroBurnSession
Returns : | a gchar or NULL. Do not free after use.

### brasero_burn_session_set_label ()

    void                brasero_burn_session_set_label      (BraseroBurnSession *session,
                                                             const gchar *label);

Sets the label for `session`.

`session` : | a BraseroBurnSession
`label` : | a gchar or `NULL`. [allow-none]

### brasero_burn_session_set_rate ()

    BraseroBurnResult   brasero_burn_session_set_rate       (BraseroBurnSession *session,
                                                             guint64 rate);

Sets the speed at which the medium should be burnt. NOTE: before using this function a BraseroDrive should have been set with `brasero_burn_session_set_burner()`.

`session` : | a BraseroBurnSession
`rate` : | a guint64
Returns : | a BraseroBurnResult. BRASERO_BURN_OK if it was successful; BRASERO_BURN_ERR otherwise.

### brasero_burn_session_get_rate ()

    guint64             brasero_burn_session_get_rate       (BraseroBurnSession *session);

Returns the speed at which the medium should be burnt. NOTE: before using this function a BraseroDrive should have been set with `brasero_burn_session_set_burner()`.

`session` : | a BraseroBurnSession
Returns : | a guint64 or 0.

## See Also

BraseroBurn, BraseroSessionCfg