GNOME.org

AutoarExtractor

AutoarExtractor — Automatically extract an archive

Functions

GQuark autoar_extractor_quark ()
AutoarExtractor * autoar_extractor_new ()
void autoar_extractor_start ()
void autoar_extractor_start_async ()
GFile * autoar_extractor_get_source_file ()
GFile * autoar_extractor_get_output_file ()
guint64 autoar_extractor_get_total_size ()
guint64 autoar_extractor_get_completed_size ()
guint autoar_extractor_get_total_files ()
guint autoar_extractor_get_completed_files ()
gboolean autoar_extractor_get_output_is_dest ()
gboolean autoar_extractor_get_delete_after_extraction ()
gint64 autoar_extractor_get_notify_interval ()
void autoar_extractor_set_output_is_dest ()
void autoar_extractor_set_delete_after_extraction ()
void autoar_extractor_set_notify_interval ()

Properties

guint completed-files Read
guint64 completed-size Read
gboolean delete-after-extraction Read / Write / Construct
gint64 notify-interval Read / Write / Construct
GFile * output-file Read / Write / Construct Only
gboolean output-is-dest Read / Write / Construct
GFile * source-file Read / Write / Construct Only
guint total-files Read
guint64 total-size Read

Signals

void cancelled Run Last
void completed Run Last
guint conflict Run Last
GObject* decide-destination Run Last
void error Run Last
void progress Run Last
void scanned Run Last

Types and Values

#define AUTOAR_TYPE_EXTRACTOR
#define AUTOAR_EXTRACTOR_ERROR
enum AutoarConflictAction
  AutoarExtractor

Object Hierarchy

    GObject
    ╰── AutoarExtractor

Includes

#include <gnome-autoar/autoar.h>

Description

The AutoarExtractor object is used to automatically extract files and directories from an archive. By default, it will only create one file or directory in the output directory. This is done to avoid clutter on the user's output directory. If the archive contains only one file, the file will be extracted to the output directory. If the archive has more than one file, the files will be extracted in a directory having the same name as the archive, except the extension. It is also possible to just extract all files to the output directory (note that this will not perform any checks) by using autoar_extractor_set_output_is_dest().

AutoarExtractor will not attempt to solve any name conflicts. If the destination directory already exists, it will proceed normally. If the destionation directory cannot be created, it will fail with an error. It is possible however to change the destination, when “decide-destination” is emitted. The signal provides the decided destination and the list of files to be extracted. The signal also allows a new output destination to be used instead of the one provided by AutoarExtractor. This is convenient for solving name conflicts and implementing specific logic based on the contents of the archive.

When AutoarExtractor stops all work, it will emit one of the three signals: “cancelled”, “error”, and “completed”. After one of these signals is received, the AutoarExtractor object should be destroyed because it cannot be used to start another archive operation. An AutoarExtractor object can only be used once and extract one archive.

Functions

autoar_extractor_quark ()

GQuark
autoar_extractor_quark (void);

Gets the AutoarExtractor Error Quark.

Returns

a GQuark.

autoar_extractor_new ()

AutoarExtractor *
autoar_extractor_new (GFile *source_file,
                      GFile *output_file);

Create a new AutoarExtractor object.

Parameters

source_file

source archive

  

output_file

output directory of extracted file or directory, or the file name of the extracted file or directory itself if you set “output-is-dest” on the returned object

  

Returns

a new AutoarExtractor object.

[transfer full]

autoar_extractor_start ()

void
autoar_extractor_start (AutoarExtractor *self,
                        GCancellable *cancellable);

Runs the archive extracting work. All callbacks will be called in the same thread as the caller of this functions.

Parameters

self

an AutoarExtractor object

  

cancellable

optional GCancellable object, or NULL to ignore

  

autoar_extractor_start_async ()

void
autoar_extractor_start_async (AutoarExtractor *self,
                              GCancellable *cancellable);

Asynchronously runs the archive extracting work. You should connect to “cancelled”, “error”, and “completed” signal to get notification when the work is terminated. All callbacks will be called in the main thread, so you can safely manipulate GTK+ widgets in the callbacks.

Parameters

self

an AutoarExtractor object

  

cancellable

optional GCancellable object, or NULL to ignore

  

autoar_extractor_get_source_file ()

GFile *
autoar_extractor_get_source_file (AutoarExtractor *self);

Gets the GFile object which represents the source archive that will be extracted for this object.

Parameters

self

an AutoarExtractor

  

Returns

a GFile.

[transfer none]

autoar_extractor_get_output_file ()

GFile *
autoar_extractor_get_output_file (AutoarExtractor *self);

This function is similar to autoar_extractor_get_output(), except for the return value is a GFile.

Parameters

self

an AutoarExtractor

  

Returns

a GFile.

[transfer none]

autoar_extractor_get_total_size ()

guint64
autoar_extractor_get_total_size (AutoarExtractor *self);

Gets the size in bytes will be written when the operation is completed.

Parameters

self

an AutoarExtractor

  

Returns

total size of extracted files in bytes

autoar_extractor_get_completed_size ()

guint64
autoar_extractor_get_completed_size (AutoarExtractor *self);

Gets the size in bytes has been written to disk.

Parameters

self

an AutoarExtractor

  

Returns

size in bytes has been written

autoar_extractor_get_total_files ()

guint
autoar_extractor_get_total_files (AutoarExtractor *self);

Gets the total number of files will be written when the operation is completed.

Parameters

self

an AutoarExtractor

  

Returns

total number of extracted files

autoar_extractor_get_completed_files ()

guint
autoar_extractor_get_completed_files (AutoarExtractor *self);

Gets the number of files has been written to disk.

Parameters

self

an AutoarExtractor

  

Returns

number of files has been written to disk

autoar_extractor_get_output_is_dest ()

gboolean
autoar_extractor_get_output_is_dest (AutoarExtractor *self);

See autoar_extractor_set_output_is_dest().

Parameters

self

an AutoarExtractor

  

Returns

TRUE if “output” is the location of extracted file or directory

autoar_extractor_get_delete_after_extraction ()

gboolean
autoar_extractor_get_delete_after_extraction
                               (AutoarExtractor *self);

Whether the source archive will be deleted after a successful extraction.

Parameters

self

an AutoarExtractor

  

Returns

TRUE if the source archive will be deleted after a succesful extraction

autoar_extractor_get_notify_interval ()

gint64
autoar_extractor_get_notify_interval (AutoarExtractor *self);

See autoar_extractor_set_notify_interval().

Parameters

self

an AutoarExtractor

  

Returns

the minimal interval in microseconds between the emission of the “progress” signal.

autoar_extractor_set_output_is_dest ()

void
autoar_extractor_set_output_is_dest (AutoarExtractor *self,
                                     gboolean output_is_dest);

By default “output-is-dest” is set to FALSE, which means only one file or directory will be generated. The destination is internally determined by analyzing the contents of the archive. If this is not wanted, “output-is-dest” can be set to TRUE, which will make “output” the destination for extracted files. In any case, the destination will be notified via “decide-destination”, when it is possible to set a new destination.

AutoarExtractor will attempt to create the destination regardless to whether its path was internally decided or not.

This function should only be called before calling autoar_extractor_start() or autoar_extractor_start_async().

Parameters

self

an AutoarExtractor

  

output_is_dest

TRUE if the location of the extracted directory or file has been already decided

  

autoar_extractor_set_delete_after_extraction ()

void
autoar_extractor_set_delete_after_extraction
                               (AutoarExtractor *self,
                                gboolean delete_if_succeed);

By default “delete-after-extraction” is set to FALSE so the source archive will not be automatically deleted if extraction succeeds.

Parameters

self

an AutoarExtractor

  

delete_after_extraction

TRUE if the source archive should be deleted after a successful extraction

  

autoar_extractor_set_notify_interval ()

void
autoar_extractor_set_notify_interval (AutoarExtractor *self,
                                      gint64 notify_interval);

Sets the minimal interval between emission of “progress” signal. This prevent too frequent signal emission, which may cause performance impact. If you do not want this feature, you can set the interval to 0, so you will receive every progress update.

Parameters

self

an AutoarExtractor

  

notify_interval

the minimal interval in microseconds

  

Types and Values

AUTOAR_TYPE_EXTRACTOR

#define AUTOAR_TYPE_EXTRACTOR autoar_extractor_get_type ()

AUTOAR_EXTRACTOR_ERROR

#define AUTOAR_EXTRACTOR_ERROR autoar_extractor_quark()

enum AutoarConflictAction

Members

AUTOAR_CONFLICT_SKIP

    

AUTOAR_CONFLICT_OVERWRITE

    

AUTOAR_CONFLICT_CHANGE_DESTINATION

    

AutoarExtractor

typedef struct _AutoarExtractor AutoarExtractor;

Property Details

The “completed-files” property

  “completed-files”          guint

Number of files has been written.

Flags: Read

Default value: 0

The “completed-size” property

  “completed-size”           guint64

Bytes written to disk.

Flags: Read

Default value: 0

The “delete-after-extraction” property

  “delete-after-extraction”  gboolean

Whether the source archive is deleted after a successful extraction.

Flags: Read / Write / Construct

Default value: FALSE

The “notify-interval” property

  “notify-interval”          gint64

Minimal time interval between progress signal.

Flags: Read / Write / Construct

Allowed values: >= 0

Default value: 100000

The “output-file” property

  “output-file”              GFile *

Output directory GFile of extracted archives.

Flags: Read / Write / Construct Only

The “output-is-dest” property

  “output-is-dest”           gboolean

Whether output direcotry is used as destination.

Flags: Read / Write / Construct

Default value: FALSE

The “source-file” property

  “source-file”              GFile *

The archive GFile to be extracted.

Flags: Read / Write / Construct Only

The “total-files” property

  “total-files”              guint

Number of files in the archive.

Flags: Read

Default value: 0

The “total-size” property

  “total-size”               guint64

Total size of the extracted files.

Flags: Read

Default value: 0

Signal Details

The “cancelled” signal

void
user_function (AutoarExtractor *self,
               gpointer         user_data)

This signal is emitted after archive extracting job is cancelled by the GCancellable.

Parameters

self

the AutoarExtractor

  

user_data

user data set when the signal handler was connected.

  

Flags: Run Last

The “completed” signal

void
user_function (AutoarExtractor *self,
               gpointer         user_data)

This signal is emitted after the archive extracting job is successfully completed.

Parameters

self

the AutoarExtractor

  

user_data

user data set when the signal handler was connected.

  

Flags: Run Last

The “conflict” signal

guint
user_function (AutoarExtractor *self,
               GFile           *file,
               gpointer         new_file,
               gpointer         user_data)

Parameters

self

the AutoarExtractor

  

file

the file that caused a conflict

  

new_file

an address to store the new destination for a conflict file

  

user_data

user data set when the signal handler was connected.

  

Returns

the action to be performed by AutoarExtractor

This signal is used to report and offer the possibility to solve name conflicts when extracting files.

Flags: Run Last

The “decide-destination” signal

GObject*
user_function (AutoarExtractor *self,
               GFile           *destination,
               gpointer         files,
               gpointer         user_data)

Parameters

self

the AutoarExtractor

  

destination

the location where files will be extracted

  

files

the list of files to be extracted. All have destination as their common prefix

  

user_data

user data set when the signal handler was connected.

  

Returns

a new destination that will overwrite the previous one, or NULL if this is not wanted

This signal is emitted when the path of the destination is determined. It is useful for solving name conflicts or for setting a new destination, based on the contents of the archive.

[transfer full]

Flags: Run Last

The “error” signal

void
user_function (AutoarExtractor *self,
               GError          *error,
               gpointer         user_data)

This signal is emitted when error occurs and all jobs should be terminated. Possible error domains are AUTOAR_EXTRACTOR_ERROR, G_IO_ERROR, and AUTOAR_LIBARCHIVE_ERROR, which represent error occurs in AutoarExtractor, GIO, and libarchive, respectively. The GError is owned by AutoarExtractor and should not be freed.

Parameters

self

the AutoarExtractor

  

error

the GError

  

user_data

user data set when the signal handler was connected.

  

Flags: Run Last

The “progress” signal

void
user_function (AutoarExtractor *self,
               guint64          completed_size,
               guint            completed_files,
               gpointer         user_data)

This signal is used to report progress of creating archives.

Parameters

self

the AutoarExtractor

  

completed_size

bytes has been written to disk

  

completed_files

number of files have been written to disk

  

user_data

user data set when the signal handler was connected.

  

Flags: Run Last

The “scanned” signal

void
user_function (AutoarExtractor *self,
               guint            files,
               gpointer         user_data)

This signal is emitted when AutoarExtractor finish scanning filename entries in the source archive.

Parameters

self

the AutoarExtractor

  

files

the number of files will be extracted from the source archive

  

user_data

user data set when the signal handler was connected.

  

Flags: Run Last

Generated by GTK-Doc V1.25.1