GCabFile: GCab Reference Manual

## GCabFile GCabFile — A file contained in the Cabinet |

## Stability Level

Stable, unless otherwise indicated

## Functions

gboolean | (*GCabFileCallback) ()
guint32 | gcab_file_get_attributes ()
gboolean | gcab_file_get_date ()
void | gcab_file_set_date ()
GDateTime * | gcab_file_get_date_time ()
void | gcab_file_set_date_time ()
const gchar * | gcab_file_get_extract_name ()
GFile * | gcab_file_get_file ()
const gchar * | gcab_file_get_name ()
guint32 | gcab_file_get_size ()
GBytes * | gcab_file_get_bytes ()
GCabFile * | gcab_file_new_with_file ()
GCabFile * | gcab_file_new_with_bytes ()
void | gcab_file_set_extract_name ()
void | gcab_file_set_attributes ()

## Types and Values

enum | GCabFileAttribute
| GCabFile

## Includes

    #include <libgcab.h>

## Description

A GCabFile is a handle to a file inside a Cabinet archive. It can either be a file that is already within an exisiting archive, or a file that reference a file on disk that will be used for a new archive creation. In the later case, `gcab_file_get_file()` must return a valid handle.

## Functions

### GCabFileCallback ()

    gboolean
    (*GCabFileCallback) (GCabFile *file,
                         gpointer user_data);

The type used for callback called when processing Cabinet archive files.

#### Parameters

file | the file being processed |
user_data | user data passed to the callback. |

### gcab_file_get_attributes ()

    guint32
    gcab_file_get_attributes (GCabFile *file);

Get the file attributes.

#### Parameters

file | a GCabFile |

#### Returns

the cabinet file attributes

Since: 0.6

### gcab_file_get_date ()

    gboolean
    gcab_file_get_date (GCabFile *file,
                        GTimeVal *result);

`gcab_file_get_date` is deprecated and should not be used in newly-written code.

Get the file date, in `result` .

#### Parameters

file | a GCabFile |
result | a GTimeVal to return date |

#### Returns

`TRUE` if `tv` was set

Since: 0.6

### gcab_file_set_date ()

    void
    gcab_file_set_date (GCabFile *file,
                        const GTimeVal *tv);

`gcab_file_set_date` is deprecated and should not be used in newly-written code.

Sets the file modification date, instead of the value provided by the GFile.

#### Parameters

file | a GCabFile |
tv | a GTimeVal |

Since: 1.0

### gcab_file_get_date_time ()

    GDateTime *
    gcab_file_get_date_time (GCabFile *file);

Gets the file date and returns it as a GDateTime..

#### Parameters

file | a GCabFile |

#### Returns

file date, or NULL if unknown.

Since: 1.4

### gcab_file_set_date_time ()

    void
    gcab_file_set_date_time (GCabFile *file,
                             GDateTime *dt);

Sets the file modification date (instead of the date provided by the GFile)

#### Parameters

file | a GCabFile |
dt | a GDateTime |

Since: 1.4

### gcab_file_get_extract_name ()

    const gchar *
    gcab_file_get_extract_name (GCabFile *file);

Get the file name to use for extraction, or `NULL`.

#### Parameters

file | a GCabFile |

#### Returns

a file name.

[allow-none]

### gcab_file_get_file ()

    GFile *
    gcab_file_get_file (GCabFile *file);

If the cabinet is being created, get the GFile associated with `file` . This must be an exisiting file that can be read, in order to be added to the archive during cabinet creation.

If `file` is from an existing cabinet, the fuction will return `NULL`.

#### Parameters

file | a GCabFile |

#### Returns

the associated GFile or `NULL`.

[transfer none]

### gcab_file_get_name ()

    const gchar *
    gcab_file_get_name (GCabFile *file);

Get the file name within the cabinet.

#### Parameters

file | a GCabFile |

#### Returns

the cabinet file name

### gcab_file_get_size ()

    guint32
    gcab_file_get_size (GCabFile *file);

Get the file size.

#### Parameters

file | a GCabFile |

#### Returns

the cabinet file size

Since: 0.6

### gcab_file_get_bytes ()

    GBytes *
    gcab_file_get_bytes (GCabFile *file);

Get the GFile associated with `file` . This will only be non-`NULL` if the GCabFile has been created using `gcab_file_new_with_bytes()`.

#### Parameters

file | a GCabFile |

#### Returns

the associated GBytes or `NULL`.

[transfer none]

Since: 1.0

### gcab_file_new_with_file ()

    GCabFile *
    gcab_file_new_with_file (const gchar *name,
                             GFile *file);

Create a GCabFile from a given GFile, to be added to a GCabCabinet for archive creation.

#### Parameters

name | name of the file within the cabinet |
file | a GFile to be added to the cabinet |

#### Returns

a new GCabFile

### gcab_file_new_with_bytes ()

    GCabFile *
    gcab_file_new_with_bytes (const gchar *name,
                              GBytes *bytes);

Create a GCabFile from a given GBytes.

If this file is to be added to an archive you should also probably use `gcab_file_set_date()` and `gcab_file_set_attributes()` to set sensible values.

#### Parameters

name | name of the file within the cabinet |
bytes | a GBytes to be added to the cabinet |

#### Returns

a new GCabFile

Since: 1.0

### gcab_file_set_extract_name ()

    void
    gcab_file_set_extract_name (GCabFile *file,
                                const gchar *name);

Sets the file name to use for extraction, instead of the name provided by the Cabinet.

#### Parameters

file | a GCabFile |
name | a file name or `NULL`. | [allow-none]

### gcab_file_set_attributes ()

    void
    gcab_file_set_attributes (GCabFile *file,
                              guint32 attr);

Set the file attributes.

#### Parameters

file | a GCabFile |
attr | the attributes, e.g. `GCAB_FILE_ATTRIBUTE_RDONLY` |

Since: 1.0

## Types and Values

### enum GCabFileAttribute

Attributes associated with the GCabFile.

#### Members

GCAB_FILE_ATTRIBUTE_RDONLY | file is read-only |
GCAB_FILE_ATTRIBUTE_HIDDEN | file is hidden |
GCAB_FILE_ATTRIBUTE_SYSTEM | file is a system file |
GCAB_FILE_ATTRIBUTE_ARCH | file modified since last backup |
GCAB_FILE_ATTRIBUTE_EXEC | run after extraction |
GCAB_FILE_ATTRIBUTE_NAME_IS_UTF | name contains UTF |

### GCabFile

    typedef struct _GCabFile GCabFile;

An opaque object, referencing a file in a Cabinet.

## See Also

GCabFolder