AutoarCompressor: gnome-autoar Reference Manual

## AutoarCompressor AutoarCompressor — Automatically compress files |

## Functions

GQuark | autoar_compressor_quark ()
AutoarCompressor * | autoar_compressor_new ()
void | autoar_compressor_start ()
void | autoar_compressor_start_async ()
GList * | autoar_compressor_get_source_files ()
GFile * | autoar_compressor_get_output_file ()
AutoarFormat | autoar_compressor_get_format ()
AutoarFilter | autoar_compressor_get_filter ()
gboolean | autoar_compressor_get_create_top_level_directory ()
guint64 | autoar_compressor_get_size ()
guint64 | autoar_compressor_get_completed_size ()
guint | autoar_compressor_get_files ()
guint | autoar_compressor_get_completed_files ()
gboolean | autoar_compressor_get_output_is_dest ()
gint64 | autoar_compressor_get_notify_interval ()
void | autoar_compressor_set_output_is_dest ()
void | autoar_compressor_set_notify_interval ()

## Properties

guint | completed-files | Read
guint64 | completed-size | Read
gboolean | create-top-level-directory | Read / Write / Construct
guint | files | Read
AutoarFilter | filter | Read / Write / Construct Only
AutoarFormat | format | Read / Write / Construct Only
gint64 | notify-interval | Read / Write / Construct
GFile * | output-file | Read / Write / Construct Only
gboolean | output-is-dest | Read / Write / Construct
guint64 | size | Read
gpointer | source-files | 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

#define | AUTOAR_TYPE_COMPRESSOR
#define | AUTOAR_COMPRESSOR_ERROR
| AutoarCompressor

## Object Hierarchy

        GObject
        ╰── AutoarCompressor

## Includes

    #include <gnome-autoar/autoar.h>

## Description

The AutoarCompressor object is used to automatically compress files and directories into an archive. The new archive can contain a top-level directory. 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 AutoarCompressor stop all work, it will emit one of the three signals: “cancelled”, “error”, and “completed”. After one of these signals is received, the AutoarCompressor object should be destroyed because it cannot be used to start another archive operation. An AutoarCompressor object can only be used once and create one archive.

## Functions

### autoar_compressor_quark ()

    GQuark
    autoar_compressor_quark (void);

Gets the AutoarCompressor Error Quark.

#### Returns

a GQuark.

### autoar_compressor_new ()

    AutoarCompressor *
    autoar_compressor_new (GList *source_files,
                           GFile *output_file,
                           AutoarFormat format,
                           AutoarFilter filter,
                           gboolean create_top_level_directory);

Create a new AutoarCompressor object.

#### Parameters

source_files | a GList of source GFiles to be archived |
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 |
format | the compression format |
filter | the compression filter |

#### Returns

a new AutoarCompressor object.

[transfer full]

### autoar_compressor_start ()

    void
    autoar_compressor_start (AutoarCompressor *self,
                             GCancellable *cancellable);

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

#### Parameters

self | an AutoarCompressor object |
cancellable | optional GCancellable object, or `NULL` to ignore |

### autoar_compressor_start_async ()

    void
    autoar_compressor_start_async (AutoarCompressor *self,
                                   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

self | an AutoarCompressor object |
cancellable | optional GCancellable object, or `NULL` to ignore |

### autoar_compressor_get_source_files ()

    GList *
    autoar_compressor_get_source_files (AutoarCompressor *self);

Gets the list of source files.

#### Parameters

self | an AutoarCompressor |

#### Returns

a GList with the source files.

[transfer none]

### autoar_compressor_get_output_file ()

    GFile *
    autoar_compressor_get_output_file (AutoarCompressor *self);

If “output_is_dest” is `FALSE`, gets the directory which contains the new archive. Otherwise, gets the the new archive. See `autoar_compressor_set_output_is_dest()`.

#### Parameters

self | an AutoarCompressor |

#### Returns

a GFile.

[transfer none]

### autoar_compressor_get_format ()

    AutoarFormat
    autoar_compressor_get_format (AutoarCompressor *self);

Gets the compression format

#### Parameters

self | an AutoarCompressor |

#### Returns

the compression format

### autoar_compressor_get_filter ()

    AutoarFilter
    autoar_compressor_get_filter (AutoarCompressor *self);

Gets the compression filter

#### Parameters

self | an AutoarCompressor |

#### Returns

the compression filter

### autoar_compressor_get_create_top_level_directory ()

    gboolean
    autoar_compressor_get_create_top_level_directory
                                   (AutoarCompressor *self);

Gets whether a top level directory will be created in the new archive.

#### Parameters

self | an AutoarCompressor |

#### Returns

whether a top level directory will be created

### autoar_compressor_get_size ()

    guint64
    autoar_compressor_get_size (AutoarCompressor *self);

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

self | an AutoarCompressor |

#### Returns

total file size in bytes

### autoar_compressor_get_completed_size ()

    guint64
    autoar_compressor_get_completed_size (AutoarCompressor *self);

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

#### Parameters

self | an AutoarCompressor |

#### Returns

file size in bytes has been read

### autoar_compressor_get_files ()

    guint
    autoar_compressor_get_files (AutoarCompressor *self);

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

self | an AutoarCompressor |

#### Returns

total number of files

### autoar_compressor_get_completed_files ()

    guint
    autoar_compressor_get_completed_files (AutoarCompressor *self);

Gets the number of files has been read

#### Parameters

self | an AutoarCompressor |

#### Returns

number of files has been read

### autoar_compressor_get_output_is_dest ()

    gboolean
    autoar_compressor_get_output_is_dest (AutoarCompressor *self);

See `autoar_compressor_set_output_is_dest()`.

#### Parameters

self | an AutoarCompressor |

#### Returns

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

### autoar_compressor_get_notify_interval ()

    gint64
    autoar_compressor_get_notify_interval (AutoarCompressor *self);

See `autoar_compressor_set_notify_interval()`.

#### Parameters

self | an AutoarCompressor |

#### Returns

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

### autoar_compressor_set_output_is_dest ()

    void
    autoar_compressor_set_output_is_dest (AutoarCompressor *self,
                                          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 AutoarCompressor to decide it for you, you can set “output-is-dest” to `TRUE`. AutoarCompressor 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_compressor_start()` or `autoar_compressor_start_async()`.

#### Parameters

self | an AutoarCompressor |
output_is_dest | `TRUE` if the location of the new archive has been already decided |

### autoar_compressor_set_notify_interval ()

    void
    autoar_compressor_set_notify_interval (AutoarCompressor *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 AutoarCompressor |
notify_interval | the minimal interval in microseconds |

## Types and Values

### AUTOAR_TYPE_COMPRESSOR

    #define AUTOAR_TYPE_COMPRESSOR autoar_compressor_get_type ()

### AUTOAR_COMPRESSOR_ERROR

    #define AUTOAR_COMPRESSOR_ERROR autoar_compressor_quark()

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

### AutoarCompressor

    typedef struct _AutoarCompressor AutoarCompressor;

## 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 `“create-top-level-directory”` property

      “create-top-level-directory” gboolean

Whether to create a top level directory.

Flags: Read / Write / Construct

Default value: FALSE

### The `“files”` property

      “files”                    guint

Number of files will be compressed.

Flags: Read

Default value: 0

### The `“filter”` property

      “filter”                   AutoarFilter

The compression filter that will be used.

Flags: Read / Write / Construct Only

Default value: AUTOAR_FILTER_NONE

### The `“format”` property

      “format”                   AutoarFormat

The compression format that will be used.

Flags: Read / Write / Construct Only

Default value: AUTOAR_FORMAT_ZIP

### 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 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-files”` property

      “source-files”             gpointer

The list of GFiles to be archived.

Flags: Read / Write / Construct Only

## Signal Details

### The `“cancelled”` signal

    void
    user_function (AutoarCompressor *self,
                   gpointer          user_data)

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

#### Parameters

self | the AutoarCompressor |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“completed”` signal

    void
    user_function (AutoarCompressor *self,
                   gpointer          user_data)

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

#### Parameters

self | the AutoarCompressor |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

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

    void
    user_function (AutoarCompressor *self,
                   GFile            *destination,
                   gpointer          user_data)

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

#### Parameters

self | the AutoarCompressor |
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 (AutoarCompressor *self,
                   GError           *error,
                   gpointer          user_data)

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

#### Parameters

self | the AutoarCompressor |
error | the GError |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“progress”` signal

    void
    user_function (AutoarCompressor *self,
                   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

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