BraseroBurnSession: Libbrasero-burn Reference Manual

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

## Functions

BraseroBurnSession * | brasero_burn_session_new ()
BraseroBurnResult | brasero_burn_session_add_track ()
BraseroBurnResult | brasero_burn_session_move_track ()
BraseroBurnResult | brasero_burn_session_remove_track ()
GSList * | brasero_burn_session_get_tracks ()
BraseroBurnResult | brasero_burn_session_get_status ()
BraseroBurnResult | brasero_burn_session_get_size ()
BraseroBurnResult | brasero_burn_session_get_input_type ()
BraseroBurnResult | brasero_burn_session_tag_lookup ()
BraseroBurnResult | brasero_burn_session_tag_add ()
BraseroBurnResult | brasero_burn_session_tag_remove ()
BraseroDrive * | brasero_burn_session_get_burner ()
void | brasero_burn_session_set_burner ()
BraseroBurnResult | brasero_burn_session_set_image_output_full ()
BraseroBurnResult | brasero_burn_session_get_output ()
BraseroImageFormat | brasero_burn_session_get_output_format ()
void | brasero_burn_session_set_flags ()
void | brasero_burn_session_add_flag ()
void | brasero_burn_session_remove_flag ()
BraseroBurnFlag | brasero_burn_session_get_flags ()
BraseroBurnResult | brasero_burn_session_set_tmpdir ()
const gchar * | brasero_burn_session_get_tmpdir ()
BraseroBurnResult | brasero_burn_session_get_burn_flags ()
BraseroBurnResult | brasero_burn_session_get_blank_flags ()
BraseroBurnResult | brasero_burn_session_can_blank ()
BraseroBurnResult | brasero_burn_session_can_burn ()
BraseroBurnResult | brasero_burn_session_input_supported ()
BraseroBurnResult | brasero_burn_session_output_supported ()
BraseroMedia | brasero_burn_session_get_required_media_type ()
guint | brasero_burn_session_get_possible_output_formats ()
BraseroImageFormat | brasero_burn_session_get_default_output_format ()
const gchar * | brasero_burn_session_get_label ()
void | brasero_burn_session_set_label ()
BraseroBurnResult | brasero_burn_session_set_rate ()
guint64 | brasero_burn_session_get_rate ()

## Properties

int | flags | Read / Write
gint64 | speed | Read / Write
char * | tmpdir | Read / Write

## Signals

void | output-changed | Run Last
void | tag-changed | Run First
void | track-added | Run Last
void | track-changed | Run Last
void | track-removed | Run Last

## Types and Values

struct | BraseroBurnSession
struct | BraseroBurnSessionClass

## Object Hierarchy

        GObject
        ╰── BraseroBurnSession
            ╰── BraseroSessionSpan

## Includes

    #include <brasero-session.h>

## 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.

## Functions

### 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` .

#### Parameters

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.

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

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]

### 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.

#### Parameters

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

#### Parameters

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`

#### Parameters

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.

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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()`).

#### Parameters

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()`).

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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()`).

#### Parameters

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.

#### Parameters

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.

#### Parameters

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`.

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

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()`.

#### Parameters

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()`.

#### Parameters

session | a BraseroBurnSession |

#### Returns

a guint64 or 0.

## Types and Values

### struct BraseroBurnSession

    struct BraseroBurnSession;

### struct BraseroBurnSessionClass

    struct BraseroBurnSessionClass {
    	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);
    };

## Property Details

### The `“flags”` property

      “flags”                    int

The flags that will be used to burn.

Owner: BraseroBurnSession

Flags: Read / Write

Allowed values: >= 0

Default value: 0

### The `“speed”` property

      “speed”                    gint64

The speed at which a disc should be burned.

Owner: BraseroBurnSession

Flags: Read / Write

Allowed values: >= 0

Default value: 0

### The `“tmpdir”` property

      “tmpdir”                   char *

The path to the temporary directory.

Owner: BraseroBurnSession

Flags: Read / Write

Default value: NULL

## Signal Details

### The `“output-changed”` signal

    void
    user_function (BraseroBurnSession *session,
                   BraseroMedium      *former_medium,
                   gpointer            user_data)

This signal gets emitted when the medium to burn to changed.

#### Parameters

session | the object which received the signal |
former_medium | the medium which was previously set |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“tag-changed”` signal

    void
    user_function (BraseroBurnSession *session,
                   char               *arg1,
                   gpointer            user_data)

This signal gets emitted when a tag changed for `session` (whether it was removed, added, or it changed).

#### Parameters

session | the object which received the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“track-added”` signal

    void
    user_function (BraseroBurnSession *session,
                   BraseroTrack       *track,
                   gpointer            user_data)

This signal gets emitted when a track is added to `session` .

#### Parameters

session | the object which received the signal |
track | the track that was added |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“track-changed”` signal

    void
    user_function (BraseroBurnSession *session,
                   BraseroTrack       *track,
                   gpointer            user_data)

This signal gets emitted when the contents of a track changed.

#### Parameters

session | the object which received the signal |
track | the track that changed |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“track-removed”` signal

    void
    user_function (BraseroBurnSession *session,
                   BraseroTrack       *track,
                   guint               former_position,
                   gpointer            user_data)

This signal gets emitted when a track is removed from `session` .

#### Parameters

session | the object which received the signal |
track | the track that was removed |
former_position | the former position of `track` |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

## See Also

BraseroBurn, BraseroSessionCfg