## 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 ()
void | autoar_extractor_set_passphrase ()

## 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
char* | request-passphrase | Run Last
void | scanned | Run Last

## Types and Values

#define | AUTOAR_TYPE_EXTRACTOR
#define | AUTOAR_EXTRACTOR_ERROR
#define | AUTOAR_NOT_AN_ARCHIVE_ERRNO
#define | AUTOAR_EMPTY_ARCHIVE_ERRNO
#define | AUTOAR_PASSPHRASE_REQUIRED_ERRNO
enum | AutoarConflictAction
| AutoarExtractor

## Object Hierarchy

        GEnum
        ╰── AutoarConflictAction
        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 with the same name as the source archive without the extension, the file will be extracted to the output directory. Otherwise the files will be extracted in a directory having the same name as the source 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 destination 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 | a GFile for the source archive |
output_file | a GFile for the directory where the files will be extracted |

#### 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);

Gets the GFile object which represents the output directory of extracted file or directory, or the extracted file or directory itself if you set “output-is-dest” on the returned object.

#### 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-file” is the destination for extracted files

### 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 created in “output-file”. 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-file” 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 “output-file” is the destination for extracted files |

### autoar_extractor_set_delete_after_extraction ()

    void
    autoar_extractor_set_delete_after_extraction
                                   (AutoarExtractor *self,
                                    gboolean delete_after_extraction);

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 |

### autoar_extractor_set_passphrase ()

    void
    autoar_extractor_set_passphrase (AutoarExtractor *self,
                                     const gchar *passphrase);

Sets a passphrase to use if the file to decompress is passphrase-protected.

#### Parameters

self | an AutoarExtractor object |
passphrase | a string with the passphrase to use |

## Types and Values

### AUTOAR_TYPE_EXTRACTOR

    #define AUTOAR_TYPE_EXTRACTOR autoar_extractor_get_type ()

### AUTOAR_EXTRACTOR_ERROR

    #define AUTOAR_EXTRACTOR_ERROR autoar_extractor_quark()

### AUTOAR_NOT_AN_ARCHIVE_ERRNO

    #define AUTOAR_NOT_AN_ARCHIVE_ERRNO 2013

### AUTOAR_EMPTY_ARCHIVE_ERRNO

    #define AUTOAR_EMPTY_ARCHIVE_ERRNO 2014

### AUTOAR_PASSPHRASE_REQUIRED_ERRNO

    #define AUTOAR_PASSPHRASE_REQUIRED_ERRNO 2015

### enum AutoarConflictAction

#### Members

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

Owner: AutoarExtractor

Flags: Read

Default value: 0

### The `“completed-size”` property

      “completed-size”           guint64

Bytes written to disk.

Owner: AutoarExtractor

Flags: Read

Default value: 0

### The `“delete-after-extraction”` property

      “delete-after-extraction”  gboolean

Whether the source archive is deleted after a successful extraction.

Owner: AutoarExtractor

Flags: Read / Write / Construct

Default value: FALSE

### The `“notify-interval”` property

      “notify-interval”          gint64

Minimal time interval between progress signal.

Owner: AutoarExtractor

Flags: Read / Write / Construct

Allowed values: >= 0

Default value: 100000

### The `“output-file”` property

      “output-file”              GFile *

The #GFile of the directory where the files will be extracted.

Owner: AutoarExtractor

Flags: Read / Write / Construct Only

### The `“output-is-dest”` property

      “output-is-dest”           gboolean

Whether #AutoarExtractor:output-file is used as destination.

Owner: AutoarExtractor

Flags: Read / Write / Construct

Default value: FALSE

### The `“source-file”` property

      “source-file”              GFile *

The #GFile of the source archive that will be extracted.

Owner: AutoarExtractor

Flags: Read / Write / Construct Only

### The `“total-files”` property

      “total-files”              guint

Number of files in the archive.

Owner: AutoarExtractor

Flags: Read

Default value: 0

### The `“total-size”` property

      “total-size”               guint64

Total size of the extracted files.

Owner: AutoarExtractor

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 | a GFile for the file that caused a conflict |
new_file | a GFile for the new destination of `file` |
user_data | user data set when the signal handler was connected. |

#### Returns

the AutoarConflictAction to be performed by AutoarExtractor

This signal is used to report and offer the possibility to solve name conflicts when extracting files. If it is not handled, the `file` will be skipped.

Flags: Run Last

### The `“decide-destination”` signal

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

#### Parameters

self | the AutoarExtractor |
destination | a GFile for the location where files will be extracted |
files | the list of GFile objects to be extracted. All have `destination` as their common prefix |
user_data | user data set when the signal handler was connected. |

#### Returns

GFile for location that will overwrite `destination` , 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 extraction.

#### 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 `“request-passphrase”` signal

    char*
    user_function (AutoarExtractor *self,
                   gpointer         user_data)

This signal is emitted when the archive extracting job needs a passphrase.

#### Parameters

self | the AutoarExtractor |
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