AptControlFile

AptControlFile — Parsing files consisting of multiple RFC-822 sections.

Stability Level

Unstable, unless otherwise indicated

Synopsis

#include <apt.h>

                    AptControlSection;
AptControlSection * apt_control_section_new             (const gchar *section,
                                                         gssize length,
                                                         const gchar **next);
void                apt_control_section_unref           (AptControlSection *section);
AptControlSection * apt_control_section_ref             (AptControlSection *section);

const gchar *       apt_control_section_get             (AptControlSection *section,
                                                         const gchar *name);
GList *             apt_control_section_get_keys        (AptControlSection *section);
gsize               apt_control_section_get_size        (AptControlSection *section);
GList *             apt_control_section_get_values      (AptControlSection *section);
const gchar *       apt_control_section_get_raw         (AptControlSection *section,
                                                         const gchar *name,
                                                         gboolean complete,
                                                         gsize *length);
gboolean            apt_control_section_has_key         (AptControlSection *section,
                                                         const gchar *name);
const gchar *       apt_control_section_raw             (AptControlSection *section,
                                                         gsize *size);

                    AptControlFile;
AptControlFile *    apt_control_file_new                (const gchar *file,
                                                         GError **error);
AptControlFile *    apt_control_file_new_for_data       (const gchar *data,
                                                         gsize length);
void                apt_control_file_free               (AptControlFile *file);
AptControlSection * apt_control_file_step               (AptControlFile *file);
AptControlSection * apt_control_file_jump               (AptControlFile *file,
                                                         goffset offset);
goffset             apt_control_file_get_offset         (AptControlFile *file);

Description

This section explains the control file parser of APT2. A control file is a file consisting of multiple RFC 822-style header sections. Those files are widely used in the Debian project for packaging purposes and other stuff as well.

Details

AptControlSection

typedef struct _AptControlSection AptControlSection;

AptControlSection is an opaque data type and may only be accessed using the following functions.

apt_control_section_new ()

AptControlSection * apt_control_section_new             (const gchar *section,
                                                         gssize length,
                                                         const gchar **next);

Parses a RFC 822 header section. In case multiple fields with the same name exist, only the last one will be available. Any newlines in front of a section are ignored.

section :

 The section that shall be parsed.

length :

 The length of section. It may be longer than the to be parsed section, it only exists to not read outside of the string.

next :

 If not NULL, it will be set to the beginning of the body of the RFC-822 message; that is, (for our use) the next section.

Returns :

 An AptControlSection containing the section.

apt_control_section_unref ()

void                apt_control_section_unref           (AptControlSection *section);

Decrements the reference count of section by one. If the reference count drops to 0, the memory used by section is freed.

section :

 An AptControlSection

apt_control_section_ref ()

AptControlSection * apt_control_section_ref             (AptControlSection *section);

Increments the reference count of section by one.

section :

 An AptControlSection

Returns :

 section.

apt_control_section_get ()

const gchar *       apt_control_section_get             (AptControlSection *section,
                                                         const gchar *name);

Looks up the name in the hash table and returns the value of the field, excluding whitespace at the beginning and the end.

section :

 An AptControlSection

name :

 The name of the field that shall be looked up.

Returns :

 The stripped value as a string or NULL if the key is not set.

apt_control_section_get_keys ()

GList *             apt_control_section_get_keys        (AptControlSection *section);

Gets a list of all keys contained in this section.

section :

 An AptControlSection

Returns :

 A GList containing the keys of this section. The data in this list is owned by the section and must not be modified. If the list is no longer needed, call g_list_free() on it.

apt_control_section_get_size ()

gsize               apt_control_section_get_size        (AptControlSection *section);

Gets the number of fields in this section.

section :

 An AptControlSection

Returns :

 The number of fields in this section.

apt_control_section_get_values ()

GList *             apt_control_section_get_values      (AptControlSection *section);

Gets a list of all values contained in this section.

section :

 An AptControlSection

Returns :

 A GList containing the values of this section. The data in this list is owned by the section and must not be modified. If the list is no longer needed, call g_list_free() on it.

apt_control_section_get_raw ()

const gchar *       apt_control_section_get_raw         (AptControlSection *section,
                                                         const gchar *name,
                                                         gboolean complete,
                                                         gsize *length);

Looks up the name in the hash table and returns the value of the field, or (if complete is TRUE) the complete field. This function is preferred over apt_control_section_get(), because it does not require string duplication.

section :

 An AptControlSection

name :

 The name of the field that shall be looked up.

complete :

 Return the complete field, including the field name.

length :

 Return location for the length of the return value; or NULL if the length is not needed (e.g. for passing to atoi()).

Returns :

 The field as a string or NULL if the key is not set. The returned string is not nul-terminated.

apt_control_section_has_key ()

gboolean            apt_control_section_has_key         (AptControlSection *section,
                                                         const gchar *name);

Checks whether section contains the field name.

section :

 An AptControlSection

name :

 The name of the option

Returns :

 TRUE if section contains name, FALSE otherwise.

apt_control_section_raw ()

const gchar *       apt_control_section_raw             (AptControlSection *section,
                                                         gsize *size);

Gets the raw section data for the current section. This is useful if a section should be displayed. In most cases, the returned data is not null-terminated.

section :

 An AptControlSection

size :

 A pointer to the gsize holding the size of the section.

Returns :

 The raw section data, not null-terminated.

AptControlFile

typedef struct _AptControlFile AptControlFile;

An opaque data structure that may only be accessed using the following functions.

Thread-safe: No

apt_control_file_new ()

AptControlFile *    apt_control_file_new                (const gchar *file,
                                                         GError **error);

Creates a new AptControlFile for parsing file.

file :

 The name of the file that should be parsed.

error :

 Location to store an error.

Returns :

 A newly allocated AptControlFile or NULL if an error occurs.

apt_control_file_new_for_data ()

AptControlFile *    apt_control_file_new_for_data       (const gchar *data,
                                                         gsize length);

Creates a new AptControlFile for parsing data.

data :

 The data that shall be parsed. Must be kept around for the life-time of the object and will not be copied.

length :

 The length of data or 0 if data is null terminated.

Returns :

 A newly allocated AptControlFile.

apt_control_file_free ()

void                apt_control_file_free               (AptControlFile *file);

Free the memory used by file.

file :

 An AptControlFile

apt_control_file_step ()

AptControlSection * apt_control_file_step               (AptControlFile *file);

Advances to the next section in the file and returns that section as a AptControlSection as returned by apt_control_section_new().

file :

 An AptControlFile

Returns :

 A newly allocated AptControlSection.

apt_control_file_jump ()

AptControlSection * apt_control_file_jump               (AptControlFile *file,
                                                         goffset offset);

Parse the header section at offset. This moves the internal file pointer to the given offset, it should thus not be mixed with calls to apt_control_file_step().

file :

 An AptControlFile

offset :

 The offset at which the section begins.

Returns :

 A newly allocated GHashTable or NULL if there are no more sections.

apt_control_file_get_offset ()

goffset             apt_control_file_get_offset         (AptControlFile *file);

Gets the absolute offset at which the current section is located.

file :

 An AptControlFile

Returns :

 The offset of the current section.
Generated by GTK-Doc V1.17