## BurnerBurnSession

BurnerBurnSession — Store parameters when burning and blanking

## Functions

BurnerBurnSession * | burner_burn_session_new ()
BurnerBurnResult | burner_burn_session_add_track ()
BurnerBurnResult | burner_burn_session_move_track ()
BurnerBurnResult | burner_burn_session_remove_track ()
GSList * | burner_burn_session_get_tracks ()
BurnerBurnResult | burner_burn_session_get_status ()
BurnerBurnResult | burner_burn_session_get_size ()
BurnerBurnResult | burner_burn_session_get_input_type ()
BurnerBurnResult | burner_burn_session_tag_lookup ()
BurnerBurnResult | burner_burn_session_tag_add ()
BurnerBurnResult | burner_burn_session_tag_remove ()
BurnerDrive * | burner_burn_session_get_burner ()
void | burner_burn_session_set_burner ()
BurnerBurnResult | burner_burn_session_set_image_output_full ()
BurnerBurnResult | burner_burn_session_get_output ()
BurnerImageFormat | burner_burn_session_get_output_format ()
void | burner_burn_session_set_flags ()
void | burner_burn_session_add_flag ()
void | burner_burn_session_remove_flag ()
BurnerBurnFlag | burner_burn_session_get_flags ()
BurnerBurnResult | burner_burn_session_set_tmpdir ()
const gchar * | burner_burn_session_get_tmpdir ()
BurnerBurnResult | burner_burn_session_get_burn_flags ()
BurnerBurnResult | burner_burn_session_get_blank_flags ()
BurnerBurnResult | burner_burn_session_can_blank ()
BurnerBurnResult | burner_burn_session_can_burn ()
BurnerBurnResult | burner_burn_session_input_supported ()
BurnerBurnResult | burner_burn_session_output_supported ()
BurnerMedia | burner_burn_session_get_required_media_type ()
guint | burner_burn_session_get_possible_output_formats ()
BurnerImageFormat | burner_burn_session_get_default_output_format ()
const gchar * | burner_burn_session_get_label ()
void | burner_burn_session_set_label ()
BurnerBurnResult | burner_burn_session_set_rate ()
guint64 | burner_burn_session_get_rate ()

## Types and Values

struct | BurnerBurnSession
struct | BurnerBurnSessionClass

## Includes

    #include <burner-session.h>

## Description

This object stores all parameters for all operations performed by BurnerBurn such as burning, blanking and checksumming. To have this object configured automatically see BurnerSessionCfg.

## Functions

### burner_burn_session_new ()

    BurnerBurnSession *
    burner_burn_session_new (void);

Returns a new BurnerBurnSession object.

#### Returns

a BurnerBurnSession.

### burner_burn_session_add_track ()

    BurnerBurnResult
    burner_burn_session_add_track (BurnerBurnSession *session,
                                   BurnerTrack *new_track,
                                   BurnerTrack *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 BurnerTrack 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 BurnerBurnSession. |
new_track | a BurnerTrack or NULL. | [allow-none]
sibling | a BurnerTrack or NULL. | [allow-none]

#### Returns

a BurnerBurnResult. BURNER_BURN_OK if the track was successfully inserted or BURNER_BURN_ERR otherwise.

### burner_burn_session_move_track ()

    BurnerBurnResult
    burner_burn_session_move_track (BurnerBurnSession *session,
                                    BurnerTrack *track,
                                    BurnerTrack *sibling);

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

#### Parameters

session | a BurnerBurnSession. |
track | a BurnerTrack. |
sibling | a BurnerTrack or NULL. | [allow-none]

#### Returns

a BurnerBurnResult. BURNER_BURN_OK if the track was successfully moved or BURNER_BURN_ERR otherwise.

### burner_burn_session_remove_track ()

    BurnerBurnResult
    burner_burn_session_remove_track (BurnerBurnSession *session,
                                      BurnerTrack *track);

Removes `track` from `session` .

#### Parameters

session | a BurnerBurnSession |
track | a BurnerTrack |

#### Returns

a BurnerBurnResult. BURNER_BURN_OK if the track was successfully removed or BURNER_BURN_ERR otherwise.

### burner_burn_session_get_tracks ()

    GSList *
    burner_burn_session_get_tracks (BurnerBurnSession *session);

Returns the list of BurnerTrack added to `session` .

#### Parameters

session | a BurnerBurnSession |

#### Returns

a GSList or BurnerTrack object. Do not unref the objects in the list nor destroy the list.

[element-type BurnerBurn.Track][transfer none]

### burner_burn_session_get_status ()

    BurnerBurnResult
    burner_burn_session_get_status (BurnerBurnSession *session,
                                    BurnerStatus *status);

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

#### Parameters

session | a BurnerBurnSession |
status | a BurnerTrackStatus |

#### Returns

a BurnerBurnResult. BURNER_BURN_OK if it was successful BURNER_BURN_NOT_READY if `track` needs more time for processing BURNER_BURN_ERR if something is wrong or if it is empty

### burner_burn_session_get_size ()

    BurnerBurnResult
    burner_burn_session_get_size (BurnerBurnSession *session,
                                  goffset *blocks,
                                  goffset *bytes);

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

#### Parameters

session | a BurnerBurnSession |
blocks | a goffset or NULL |
bytes | a goffset or NULL |

#### Returns

a BurnerBurnResult. BURNER_BURN_OK if it was successful BURNER_BURN_NOT_READY if `track` needs more time for processing the size BURNER_BURN_ERR if something is wrong or if it is empty

### burner_burn_session_get_input_type ()

    BurnerBurnResult
    burner_burn_session_get_input_type (BurnerBurnSession *session,
                                        BurnerTrackType *type);

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

#### Parameters

session | a BurnerBurnSession |
type | a BurnerTrackType or NULL |

#### Returns

a BurnerBurnResult. BURNER_BURN_OK if it was successful

### burner_burn_session_tag_lookup ()

    BurnerBurnResult
    burner_burn_session_tag_lookup (BurnerBurnSession *session,
                                    const gchar *tag,
                                    GValue **value);

Retrieves a value associated with `session` through `burner_session_tag_add()` and stores it in `value` . Do not destroy `value` afterwards as it is not a copy.

#### Parameters

session | a BurnerBurnSession |
tag | a gchar * |
value | a GValue |

#### Returns

a BurnerBurnResult. BURNER_BURN_OK if the retrieval was successful BURNER_BURN_ERR otherwise

### burner_burn_session_tag_add ()

    BurnerBurnResult
    burner_burn_session_tag_add (BurnerBurnSession *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 BurnerBurnSession object takes ownership of `value` . See burner-tags.h for a list of knowns tags.

#### Parameters

session | a BurnerBurnSession |
tag | a gchar * |
value | a GValue * |

#### Returns

a BurnerBurnResult. BURNER_BURN_OK if it was successful, BURNER_BURN_ERR otherwise.

### burner_burn_session_tag_remove ()

    BurnerBurnResult
    burner_burn_session_tag_remove (BurnerBurnSession *session,
                                    const gchar *tag);

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

#### Parameters

session | a BurnerBurnSession |
tag | a gchar * |

#### Returns

a BurnerBurnResult. BURNER_BURN_OK if the retrieval was successful BURNER_BURN_ERR otherwise

### burner_burn_session_get_burner ()

    BurnerDrive *
    burner_burn_session_get_burner (BurnerBurnSession *session);

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

#### Parameters

session | a BurnerBurnSession |

#### Returns

a BurnerDrive or NULL. Do not unref after use.

[transfer none][allow-none]

### burner_burn_session_set_burner ()

    void
    burner_burn_session_set_burner (BurnerBurnSession *session,
                                    BurnerDrive *drive);

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

#### Parameters

session | a BurnerBurnSession |
drive | a BurnerDrive |

### burner_burn_session_set_image_output_full ()

    BurnerBurnResult
    burner_burn_session_set_image_output_full
                                   (BurnerBurnSession *session,
                                    BurnerImageFormat 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 BurnerDrive for `session` will be the fake BurnerDrive.

#### Parameters

session | a BurnerBurnSession. |
format | a BurnerImageFormat. |
image | a gchar or NULL. | [allow-none]
toc | a gchar or NULL. | [allow-none]

#### Returns

a BurnerBurnResult. BURNER_BURN_OK if it was successfully set; BURNER_BURN_ERR otherwise.

### burner_burn_session_get_output ()

    BurnerBurnResult
    burner_burn_session_get_output (BurnerBurnSession *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 BurnerDrive should have been set with `burner_burn_session_set_burner()` and it should be the fake drive (see `burner_drive_is_fake()`).

#### Parameters

session | a BurnerBurnSession. |
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 BurnerBurnResult. BURNER_BURN_OK if it was successful; BURNER_BURN_ERR otherwise.

### burner_burn_session_get_output_format ()

    BurnerImageFormat
    burner_burn_session_get_output_format (BurnerBurnSession *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 BurnerDrive should have been set with `burner_burn_session_set_burner()` and it should be the fake drive (see `burner_drive_is_fake()`).

#### Parameters

session | a BurnerBurnSession |

#### Returns

a BurnerImageFormat. The format of the image to be written.

### burner_burn_session_set_flags ()

    void
    burner_burn_session_set_flags (BurnerBurnSession *session,
                                   BurnerBurnFlag flags);

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

#### Parameters

session | a BurnerBurnSession |
flags | a BurnerBurnFlag |

### burner_burn_session_add_flag ()

    void
    burner_burn_session_add_flag (BurnerBurnSession *session,
                                  BurnerBurnFlag flags);

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

#### Parameters

session | a BurnerBurnSession |
flags | a BurnerBurnFlag |

### burner_burn_session_remove_flag ()

    void
    burner_burn_session_remove_flag (BurnerBurnSession *session,
                                     BurnerBurnFlag flags);

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

#### Parameters

session | a BurnerBurnSession |
flags | a BurnerBurnFlag |

### burner_burn_session_get_flags ()

    BurnerBurnFlag
    burner_burn_session_get_flags (BurnerBurnSession *session);

Returns the current flags set for `session` .

#### Parameters

session | a BurnerBurnSession |

#### Returns

a BurnerBurnFlag.

### burner_burn_session_set_tmpdir ()

    BurnerBurnResult
    burner_burn_session_set_tmpdir (BurnerBurnSession *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 BurnerBurnSession |
path | a gchar or NULL |

#### Returns

a BurnerBurnResult. BURNER_BURN_OK if it was successfully set; BURNER_BURN_ERR otherwise.

### burner_burn_session_get_tmpdir ()

    const gchar *
    burner_burn_session_get_tmpdir (BurnerBurnSession *session);

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

#### Parameters

session | a BurnerBurnSession |

#### Returns

a gchar. The path to the temporary directory.

### burner_burn_session_get_burn_flags ()

    BurnerBurnResult
    burner_burn_session_get_burn_flags (BurnerBurnSession *session,
                                        BurnerBurnFlag *supported,
                                        BurnerBurnFlag *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 BurnerBurnSession |
supported | a BurnerBurnFlag or NULL |
compulsory | a BurnerBurnFlag or NULL |

#### Returns

a BurnerBurnResult. BURNER_BURN_OK if the retrieval was successful. BURNER_BURN_ERR otherwise.

### burner_burn_session_get_blank_flags ()

    BurnerBurnResult
    burner_burn_session_get_blank_flags (BurnerBurnSession *session,
                                         BurnerBurnFlag *supported,
                                         BurnerBurnFlag *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 BurnerDrive (set with `burner_burn_session_set_burner()`).

#### Parameters

session | a BurnerBurnSession |
supported | a BurnerBurnFlag |
compulsory | a BurnerBurnFlag |

#### Returns

a BurnerBurnResult. BURNER_BURN_OK if the retrieval was successful. BURNER_BURN_ERR otherwise.

### burner_burn_session_can_blank ()

    BurnerBurnResult
    burner_burn_session_can_blank (BurnerBurnSession *session);

Given the various parameters stored in `session` , this function checks whether the medium in the BurnerDrive (set with `burner_burn_session_set_burner()`) can be blanked.

#### Parameters

session | a BurnerBurnSession |

#### Returns

a BurnerBurnResult. BURNER_BURN_OK if it is possible. BURNER_BURN_ERR otherwise.

### burner_burn_session_can_burn ()

    BurnerBurnResult
    burner_burn_session_can_burn (BurnerBurnSession *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 BurnerDrive (set through `burner_burn_session_set_burner()`). If `check_flags` determine the behavior of this function.

#### Parameters

session | a BurnerBurnSession |
check_flags | a gboolean |

#### Returns

a BurnerBurnResult. BURNER_BURN_OK if it is possible. BURNER_BURN_ERR otherwise.

### burner_burn_session_input_supported ()

    BurnerBurnResult
    burner_burn_session_input_supported (BurnerBurnSession *session,
                                         BurnerTrackType *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 BurnerDrive (set through `burner_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 BurnerBurnSession |
input | a BurnerTrackType |
check_flags | a gboolean |

#### Returns

a BurnerBurnResult. BURNER_BURN_OK if it is possible. BURNER_BURN_ERR otherwise.

### burner_burn_session_output_supported ()

    BurnerBurnResult
    burner_burn_session_output_supported (BurnerBurnSession *session,
                                          BurnerTrackType *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 BurnerBurnSession * |
output | a BurnerTrackType * |

#### Returns

BURNER_BURN_OK if the medium type or the image type can be used as an output.

### burner_burn_session_get_required_media_type ()

    BurnerMedia
    burner_burn_session_get_required_media_type
                                   (BurnerBurnSession *session);

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

#### Parameters

session | a BurnerBurnSession |

#### Returns

a BurnerMedia

### burner_burn_session_get_possible_output_formats ()

    guint
    burner_burn_session_get_possible_output_formats
                                   (BurnerBurnSession *session,
                                    BurnerImageFormat *formats);

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

#### Parameters

session | a BurnerBurnSession |
formats | a BurnerImageFormat |

#### Returns

a guint. The number of formats available.

### burner_burn_session_get_default_output_format ()

    BurnerImageFormat
    burner_burn_session_get_default_output_format
                                   (BurnerBurnSession *session);

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

#### Parameters

session | a BurnerBurnSession |

#### Returns

a BurnerImageFormat

### burner_burn_session_get_label ()

    const gchar *
    burner_burn_session_get_label (BurnerBurnSession *session);

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

#### Parameters

session | a BurnerBurnSession |

#### Returns

a gchar or NULL. Do not free after use.

### burner_burn_session_set_label ()

    void
    burner_burn_session_set_label (BurnerBurnSession *session,
                                   const gchar *label);

Sets the label for `session` .

#### Parameters

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

### burner_burn_session_set_rate ()

    BurnerBurnResult
    burner_burn_session_set_rate (BurnerBurnSession *session,
                                  guint64 rate);

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

#### Parameters

session | a BurnerBurnSession |
rate | a guint64 |

#### Returns

a BurnerBurnResult. BURNER_BURN_OK if it was successful; BURNER_BURN_ERR otherwise.

### burner_burn_session_get_rate ()

    guint64
    burner_burn_session_get_rate (BurnerBurnSession *session);

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

#### Parameters

session | a BurnerBurnSession |

#### Returns

a guint64 or 0.

## Types and Values

### struct BurnerBurnSession

    struct BurnerBurnSession {
    	GObject parent;
    };

### struct BurnerBurnSessionClass

    struct BurnerBurnSessionClass {
    	GObjectClass parent_class;

    	/** Virtual functions **/
    	BurnerBurnResult (*set_output_image) (BurnerBurnSession *session,
    							 BurnerImageFormat format,
    							 const gchar *image,
    							 const gchar *toc);
    	BurnerBurnResult (*get_output_path) (BurnerBurnSession *session,
    							 gchar **image,
    							 gchar **toc);
    	BurnerImageFormat (*get_output_format) (BurnerBurnSession *session);

    	/** Signals **/
    	void			(*tag_changed)		(BurnerBurnSession *session,
    					                 const gchar *tag);
    	void			(*track_added)		(BurnerBurnSession *session,
    							 BurnerTrack *track);
    	void			(*track_removed) (BurnerBurnSession *session,
    							 BurnerTrack *track,
    							 guint former_position);
    	void			(*track_changed) (BurnerBurnSession *session,
    							 BurnerTrack *track);
    	void			(*output_changed) (BurnerBurnSession *session,
    							 BurnerMedium *former_medium);
    };

## See Also

BurnerBurn, BurnerSessionCfg