AutoarExtractor: gnome-autoar Reference Manual

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

    gpointer
    user_function (AutoarExtractor *autoarextractor,
                   gpointer         user_data)

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