AutoarCreate

AutoarCreate — Automatically create 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
GStrv source Read / Write / Construct Only
GPtrArray * source-file 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

Types and Values

Object Hierarchy

    GObject
    ╰── AutoarCreate

Includes

#include <gnome-autoar/autoar.h>

Description

The AutoarCreate object is used to automatically create an archive from files and directories. The new archive will contain a top-level directory, and its file format can be set via autoar_pref_set_default_format() and autoar_pref_set_default_filter() on the provided AutoarPref object. Applying multiple filters is currently not supported because most applications do not need this function. GIO is used for both read and write operations. A few POSIX functions are also used to get more information from files if GIO does not provide relevant functions.

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

Functions

autoar_create_quark ()

GQuark
autoar_create_quark (void);

Gets the AutoarCreate Error Quark.

Returns

a GQuark.


autoar_create_new ()

AutoarCreate *
autoar_create_new (AutoarPref *arpref,
                   const char *output,
                   ...);

Create a new AutoarCreate object.

Parameters

arpref

an AutoarPref object used to decide the output archive format

 

output

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

 

...

a NULL-terminated list of paths of source files to be archived

 

Returns

a new AutoarCreate object.

[transfer full]


autoar_create_new_file ()

AutoarCreate *
autoar_create_new_file (AutoarPref *arpref,
                        GFile *output_file,
                        ...);

Create a new AutoarCreate object.

Parameters

arpref

an AutoarPref object used to decide the output archive format

 

output_file

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

 

...

a NULL-terminated list of GFile of source files to be archived

 

Returns

a new AutoarCreate object.

[transfer full]


autoar_create_newv ()

AutoarCreate *
autoar_create_newv (AutoarPref *arpref,
                    const char *output,
                    const GStrv source);

Create a new AutoarCreate object.

Parameters

arpref

an AutoarPref object used to decide the output archive format

 

output

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

 

source

a NULL-terminated array of paths of source files to be archived

 

Returns

a new AutoarCreate object.

[transfer full]


autoar_create_new_filev ()

AutoarCreate *
autoar_create_new_filev (AutoarPref *arpref,
                         GFile *output_file,
                         GFile **source_file);

Create a new AutoarCreate object.

Parameters

arpref

an AutoarPref object used to decide the output archive format

 

output_file

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

 

source_file

a NULL-terminated array of GFile of source files to be archived

 

Returns

a new AutoarCreate object.

[transfer full]


autoar_create_start ()

void
autoar_create_start (AutoarCreate *arcreate,
                     GCancellable *cancellable);

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

Parameters

arcreate

an AutoarCreate object

 

cancellable

optional GCancellable object, or NULL to ignore

 

autoar_create_start_async ()

void
autoar_create_start_async (AutoarCreate *arcreate,
                           GCancellable *cancellable);

Asynchronously runs the archive creating 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

arcreate

an AutoarCreate object

 

cancellable

optional GCancellable object, or NULL to ignore

 

autoar_create_get_source ()

GStrv
autoar_create_get_source (AutoarCreate *arcreate);

Gets the source files will be archived for this object. It may be an array of filenames or URIs.

Parameters

arcreate

an AutoarCreate

 

Returns

a NULL-terminated array of strings.

[transfer none]


autoar_create_get_source_file ()

GPtrArray *
autoar_create_get_source_file (AutoarCreate *arcreate);

This function is similar to autoar_create_get_source(), except for the return value is an array of GFile.

Parameters

arcreate

an AutoarCreate

 

Returns

a GPtrArray, which is an array of GFile.

[element-type GLib.PtrArray][transfer none]


autoar_create_get_output ()

char *
autoar_create_get_output (AutoarCreate *arcreate);

If “output_is_dest” is FALSE, gets the directory which contains the new archive. Otherwise, get the filename of the new archive. See autoar_create_set_output_is_dest().

Parameters

arcreate

an AutoarCreate

 

Returns

a filename.

[transfer none]


autoar_create_get_output_file ()

GFile *
autoar_create_get_output_file (AutoarCreate *arcreate);

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

Parameters

arcreate

an AutoarCreate

 

Returns

a GFile.

[transfer none]


autoar_create_get_size ()

guint64
autoar_create_get_size (AutoarCreate *arcreate);

Gets the size in bytes will be read when the operation is completed. This value is currently unset, so calling this function is useless.

Parameters

arcreate

an AutoarCreate

 

Returns

total file size in bytes


autoar_create_get_completed_size ()

guint64
autoar_create_get_completed_size (AutoarCreate *arcreate);

Gets the size in bytes has been read from the source files and directories.

Parameters

arcreate

an AutoarCreate

 

Returns

file size in bytes has been read


autoar_create_get_files ()

guint
autoar_create_get_files (AutoarCreate *arcreate);

Gets the number of files will be read when the operation is completed. This value is currently unset, so calling this function is useless.

Parameters

arcreate

an AutoarCreate

 

Returns

total number of files


autoar_create_get_completed_files ()

guint
autoar_create_get_completed_files (AutoarCreate *arcreate);

Gets the number of files has been read

Parameters

arcreate

an AutoarCreate

 

Returns

number of files has been read


autoar_create_get_output_is_dest ()

gboolean
autoar_create_get_output_is_dest (AutoarCreate *arcreate);

See autoar_create_set_output_is_dest().

Parameters

arcreate

an AutoarCreate

 

Returns

TRUE if “output” is the location of the new archive.


autoar_create_get_notify_interval ()

gint64
autoar_create_get_notify_interval (AutoarCreate *arcreate);

See autoar_create_set_notify_interval().

Parameters

arcreate

an AutoarCreate

 

Returns

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


autoar_create_set_output_is_dest ()

void
autoar_create_set_output_is_dest (AutoarCreate *arcreate,
                                  gboolean output_is_dest);

By default “output-is-dest” is set to FALSE, which means the new archive will be created as a regular file under “output” directory. The name of the new archive 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 new archive, and you do not want AutoarCreate to decide it for you, you can set “output-is-dest” to TRUE. AutoarCreate will use “output” as the location of the new archive, 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_create_start() or autoar_create_start_async().

Parameters

arcreate

an AutoarCreate

 

output_is_dest

TRUE if the location of the new archive has been already decided

 

autoar_create_set_notify_interval ()

void
autoar_create_set_notify_interval (AutoarCreate *arcreate,
                                   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

arcreate

an AutoarCreate

 

notify_interval

the minimal interval in microseconds

 

Types and Values

AUTOAR_CREATE_ERROR

#define AUTOAR_CREATE_ERROR autoar_create_quark()

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

Property Details

The “completed-files” property

  “completed-files”          guint

Number of files has been read.

Flags: Read

Default value: 0


The “completed-size” property

  “completed-size”           guint64

Bytes has read from disk.

Flags: Read

Default value: 0


The “files” property

  “files”                    guint

Number of files will be compressed.

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 created archive.

Flags: Read / Write / Construct Only

Default value: NULL


The “output-file” property

  “output-file”              GFile *

Output directory (GFile) of created archive.

Flags: Read / Write / Construct Only


The “output-is-dest” property

  “output-is-dest”           gboolean

Whether output file is used as destination.

Flags: Read / Write / Construct

Default value: FALSE


The “size” property

  “size”                     guint64

Total bytes will be read from disk.

Flags: Read

Default value: 0


The “source” property

  “source”                   GStrv

The source files and directories to be archived.

Flags: Read / Write / Construct Only


The “source-file” property

  “source-file”              GPtrArray *

The source GFiles to be archived.

Flags: Read / Write / Construct Only

Signal Details

The “cancelled” signal

void
user_function (AutoarCreate *arcreate,
               gpointer      user_data)

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

Parameters

arcreate

the AutoarCreate

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “completed” signal

void
user_function (AutoarCreate *arcreate,
               gpointer      user_data)

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

Parameters

arcreate

the AutoarCreate

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “decide-dest” signal

void
user_function (AutoarCreate *arcreate,
               GFile        *destination,
               gpointer      user_data)

This signal is emitted when the location of the new archive is determined.

Parameters

arcreate

the AutoarCreate

 

destination

the location of the new archive

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “error” signal

void
user_function (AutoarCreate *arcreate,
               GError       *error,
               gpointer      user_data)

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

Parameters

arcreate

the AutoarCreate

 

error

the GError

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “progress” signal

void
user_function (AutoarCreate *arcreate,
               guint64       completed_size,
               guint         completed_files,
               gpointer      user_data)

This signal is used to report progress of creating archives. The value of completed_size and completed_files are the same as the “completed_size” and “completed_files” properties, respectively.

Parameters

arcreate

the AutoarCreate

 

completed_size

bytes has been read from source files and directories

 

completed_files

number of files and directories has been read

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last