AutoarExtract

AutoarExtract — Automatically extract an archive

Functions

Properties

guint completed-files Read
guint64 completed-size Read
guint files Read
gint64 notify-interval Read / Write / Construct
gchar * output Read / Write / Construct Only
GFile * output-file Read / Write / Construct Only
gboolean output-is-dest Read / Write / Construct
guint64 size Read
gchar * source Read / Write / Construct Only
GFile * source-file Read / Write / Construct Only
gboolean source-is-mem Read / Write / Construct Only

Signals

void cancelled Run Last
void completed Run Last
void decide-dest Run Last
void error Run Last
void progress Run Last
void scanned Run Last

Types and Values

Object Hierarchy

    GObject
    ╰── AutoarExtract

Includes

#include <gnome-autoar/autoar.h>

Description

The AutoarExtract object is used to automatically extract files and directories from an archive. It will create a file in the output directory if the archive only contains one file, or it will create a directory in the output directory if the archive contains more than one file. AutoarExtract create only one file or directory in the output directory, so the output directory will not be messed. All absolute paths in archives will be converted to relative paths and all extracted files will be placed under the directory notified by “decide-dest”. The created file or directory name will be generated based on the name of the source archive, so users can easily figure out the relation between the archive and the extracted files. AutoarExtract can also ignore specific file name pattern when extrating, or delete the source archive after extracting, depending on the settings provided by the AutoarPref object.

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

Functions

autoar_extract_quark ()

GQuark
autoar_extract_quark (void);

Gets the AutoarExtract Error Quark.

Returns

a GQuark.


autoar_extract_new ()

AutoarExtract *
autoar_extract_new (const char *source,
                    const char *output,
                    AutoarPref *arpref);

Extract a new AutoarExtract object.

Parameters

source

source archive

 

output

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

 

arpref

an AutoarPref object

 

Returns

a new AutoarExtract object.

[transfer full]


autoar_extract_new_file ()

AutoarExtract *
autoar_extract_new_file (GFile *source_file,
                         GFile *output_file,
                         AutoarPref *arpref);

Create a new AutoarExtract 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

 

arpref

an AutoarPref object

 

Returns

a new AutoarExtract object.

[transfer full]


autoar_extract_new_memory ()

AutoarExtract *
autoar_extract_new_memory (const void *buffer,
                           gsize buffer_size,
                           const char *source_name,
                           const char *output,
                           AutoarPref *arpref);

Create a new AutoarExtract object. source_name does not need to be a full path. The file which it represents does not need to exist, either. This argument is only used to decide the name of the extracted file or directory, and it is useless if you set “output-is-dest” to TRUE.

Parameters

buffer

memory buffer holding the source archive

 

buffer_size

the size of the source archive memory buffer

 

source_name

the name of the source archive

 

output

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

 

arpref

an AutoarPref object

 

Returns

a new AutoarExtract object.

[transfer full]


autoar_extract_new_memory_file ()

AutoarExtract *
autoar_extract_new_memory_file (const void *buffer,
                                gsize buffer_size,
                                const char *source_name,
                                GFile *output_file,
                                AutoarPref *arpref);

Create a new AutoarExtract object. This function is similar to autoar_extract_new_memory() except for the argument for the output directory is GFile.

Parameters

buffer

memory buffer holding the source archive

 

buffer_size

the size of the source archive memory buffer

 

source_name

the name of the 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

 

arpref

an AutoarPref object

 

Returns

a new AutoarExtract object.

[transfer full]


autoar_extract_start ()

void
autoar_extract_start (AutoarExtract *arextract,
                      GCancellable *cancellable);

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

Parameters

arextract

an AutoarExtract object

 

cancellable

optional GCancellable object, or NULL to ignore

 

autoar_extract_start_async ()

void
autoar_extract_start_async (AutoarExtract *arextract,
                            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

arextract

an AutoarExtract object

 

cancellable

optional GCancellable object, or NULL to ignore

 

autoar_extract_free_source_buffer ()

void
autoar_extract_free_source_buffer (AutoarExtract *arextract,
                                   GDestroyNotify free_func);

Free the source memory archive provided in autoar_extract_new_memory() or autoar_extract_new_memory_file(). This functions should only be called after the extracting job is completed. That is, you should only call this function after you receives one of “cancelled”, “error”, or “completed” signal.

Parameters

arextract

an AutoarExtract object

 

free_func

a function to free the memory buffer

 

autoar_extract_get_source ()

char *
autoar_extract_get_source (AutoarExtract *arextract);

If “source_is_mem” is TRUE, gets the descriptive string for the source memory buffer. Otherwise, gets the source file will be extracted for this object. It may be a filename or URI.

Parameters

arextract

an AutoarExtract

 

Returns

a string.

[transfer none]


autoar_extract_get_source_file ()

GFile *
autoar_extract_get_source_file (AutoarExtract *arextract);

If “source_is_mem” is TRUE, gets the GFile object generated using the value of “source”. The returned GFile is not usable at all. Otherwise, gets the GFile object which represents the source archive will be extracted for this object.

Parameters

arextract

an AutoarExtract

 

Returns

a GFile.

[transfer none]


autoar_extract_get_output ()

char *
autoar_extract_get_output (AutoarExtract *arextract);

If “output_is_dest” is FALSE, gets the directory which contains the extracted file or directory. Otherwise, get the filename of the extracted file or directory itself. See autoar_extract_set_output_is_dest().

Parameters

arextract

an AutoarExtract

 

Returns

a filename.

[transfer none]


autoar_extract_get_output_file ()

GFile *
autoar_extract_get_output_file (AutoarExtract *arextract);

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

Parameters

arextract

an AutoarExtract

 

Returns

a GFile.

[transfer none]


autoar_extract_get_size ()

guint64
autoar_extract_get_size (AutoarExtract *arextract);

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

Parameters

arextract

an AutoarExtract

 

Returns

total size of extracted files in bytes


autoar_extract_get_completed_size ()

guint64
autoar_extract_get_completed_size (AutoarExtract *arextract);

Gets the size in bytes has been written to disk.

Parameters

arextract

an AutoarExtract

 

Returns

size in bytes has been written


autoar_extract_get_files ()

guint
autoar_extract_get_files (AutoarExtract *arextract);

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

Parameters

arextract

an AutoarExtract

 

Returns

total number of extracted files


autoar_extract_get_completed_files ()

guint
autoar_extract_get_completed_files (AutoarExtract *arextract);

Gets the number of files has been written to disk.

Parameters

arextract

an AutoarExtract

 

Returns

number of files has been written to disk


autoar_extract_get_source_is_mem ()

gboolean
autoar_extract_get_source_is_mem (AutoarExtract *arextract);

Gets whether the source archive is a memory buffer.

Parameters

arextract

an AutoarExtract

 

Returns

TRUE if the source archive is a memory buffer.


autoar_extract_get_output_is_dest ()

gboolean
autoar_extract_get_output_is_dest (AutoarExtract *arextract);

See autoar_extract_set_output_is_dest().

Parameters

arextract

an AutoarExtract

 

Returns

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


autoar_extract_get_notify_interval ()

gint64
autoar_extract_get_notify_interval (AutoarExtract *arextract);

See autoar_extract_set_notify_interval().

Parameters

arextract

an AutoarExtract

 

Returns

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


autoar_extract_set_output_is_dest ()

void
autoar_extract_set_output_is_dest (AutoarExtract *arextract,
                                   gboolean output_is_dest);

By default “output-is-dest” is set to FALSE, which means the extracted files will be created as a single file or a single top-level directory under “output” directory. The name of the extracted file or directory will be automatically generated and you will be notified via “decide-dest” when the name is decided. If you have already decided the location of the extracted file or directory, and you do not want AutoarExtract to decide it for you, you can set “output-is-dest” to TRUE. AutoarExtract will use “output” as the location of the extracted directory or file, and it will neither check whether the file exists nor create the necessary directories for you. This function should only be called before calling autoar_extract_start() or autoar_extract_start_async().

Parameters

arextract

an AutoarExtract

 

output_is_dest

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

 

autoar_extract_set_notify_interval ()

void
autoar_extract_set_notify_interval (AutoarExtract *arextract,
                                    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

arextract

an AutoarExtract

 

notify_interval

the minimal interval in microseconds

 

Types and Values

AUTOAR_EXTRACT_ERROR

#define AUTOAR_EXTRACT_ERROR autoar_extract_quark()

Error domain for AutoarExtract. Not all error occurs in AutoarExtract uses this domain. It is only used for error occurs in AutoarExtract itself. See “error” signal for more information.

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 “files” property

  “files”                    guint

Number of files in the archive.

Flags: Read

Default value: 0


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” property

  “output”                   gchar *

Output directory of extracted archive.

Flags: Read / Write / Construct Only

Default value: NULL


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 “size” property

  “size”                     guint64

Size of the extracted files.

Flags: Read

Default value: 0


The “source” property

  “source”                   gchar *

The archive file to be extracted.

Flags: Read / Write / Construct Only

Default value: NULL


The “source-file” property

  “source-file”              GFile *

The archive GFile to be extracted.

Flags: Read / Write / Construct Only


The “source-is-mem” property

  “source-is-mem”            gboolean

Whether source file is in memory.

Flags: Read / Write / Construct Only

Default value: FALSE

Signal Details

The “cancelled” signal

void
user_function (AutoarExtract *arextract,
               gpointer       user_data)

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

Parameters

arextract

the AutoarExtract

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “completed” signal

void
user_function (AutoarExtract *arextract,
               gpointer       user_data)

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

Parameters

arextract

the AutoarExtract

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “decide-dest” signal

void
user_function (AutoarExtract *arextract,
               GFile         *destination,
               gpointer       user_data)

This signal is emitted when the location of the extracted directory or file is determined.

Parameters

arextract

the AutoarExtract

 

destination

the location of the extracted directory or file

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “error” signal

void
user_function (AutoarExtract *arextract,
               GError        *error,
               gpointer       user_data)

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

Parameters

arextract

the AutoarExtract

 

error

the GError

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “progress” signal

void
user_function (AutoarExtract *arextract,
               guint64        completed_size,
               guint          completed_files,
               gpointer       user_data)

This signal is used to report progress of creating archives.

Parameters

arextract

the AutoarExtract

 

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 (AutoarExtract *arextract,
               guint          files,
               gpointer       user_data)

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

Parameters

arextract

the AutoarExtract

 

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