## AgsFile

AgsFile — read/write XML file

## Stability Level

Stable, unless otherwise indicated

## Functions

#define | AGS_FILE_GET_OBJ_MUTEX()
void | ags_file_set_filename ()
gchar * | ags_file_get_filename ()
void | ags_file_set_encoding ()
gchar * | ags_file_get_encoding ()
void | ags_file_set_audio_format ()
gchar * | ags_file_get_audio_format ()
void | ags_file_set_audio_encoding ()
gchar * | ags_file_get_audio_encoding ()
void | ags_file_set_xml_doc ()
xmlDoc * | ags_file_get_xml_doc ()
gchar * | ags_file_str2md5 ()
void | ags_file_add_id_ref ()
GObject * | ags_file_find_id_ref_by_node ()
GObject * | ags_file_find_id_ref_by_xpath ()
GObject * | ags_file_find_id_ref_by_reference ()
void | ags_file_add_lookup ()
void | ags_file_add_launch ()
xmlDoc * | ags_file_xml_new_doc ()
xmlNode * | ags_file_xml_new_node ()
xmlNode * | ags_file_xml_get_root_element ()
void | ags_file_xml_set_root_element ()
void | ags_file_xml_add_child ()
gchar * | ags_file_xml_get_node_name ()
xmlNode * | ags_file_xml_get_node_parent ()
xmlNode * | ags_file_xml_get_node_next ()
xmlNode * | ags_file_xml_get_node_children ()
gchar * | ags_file_xml_get_prop ()
void | ags_file_xml_set_prop ()
gchar * | ags_file_xml_get_content ()
void | ags_file_xml_set_content ()
void | ags_file_open ()
void | ags_file_open_from_data ()
void | ags_file_rw_open ()
void | ags_file_open_filename ()
void | ags_file_close ()
void | ags_file_write ()
void | ags_file_write_concurrent ()
void | ags_file_write_resolve ()
void | ags_file_read ()
void | ags_file_read_resolve ()
void | ags_file_read_start ()
void | ags_file_read_config ()
void | ags_file_write_config ()
void | ags_file_read_application_context ()
void | ags_file_write_application_context ()
AgsFile * | ags_file_new ()

## Properties

char * | audio-encoding | Read / Write
char * | audio-format | Read / Write
char * | encoding | Read / Write
char * | filename | Read / Write
gpointer | xml-doc | Read / Write

## Signals

void | open | Run Last
void | open-from-data | Run Last
void | read | Run Last
void | read-resolve | Run Last
void | read-start | Run Last
void | rw-open | Run Last
void | write | Run Last
void | write-concurrent | Run Last
void | write-resolve | Run Last

## Types and Values

#define | AGS_FILE_DEFAULT_APP_ENCODING
#define | AGS_FILE_DEFAULT_ENCODING
#define | AGS_FILE_DEFAULT_DTD
#define | AGS_FILE_CHECKSUM_LENGTH
#define | AGS_FILE_DEFAULT_AUDIO_FORMAT
#define | AGS_FILE_DEFAULT_AUDIO_ENCODING
#define | AGS_FILE_CHARSET_CONVERTER_MAX_STRING_LENGTH
#define | AGS_FILE_CHARSET_CONVERTER_MAX_CONTENT_LENGTH
enum | AgsFileFlags
#define | AGS_FILE_ERROR
enum | AgsFileError

## Object Hierarchy

        GFlags
        ╰── AgsFileFlags
        GObject
        ╰── AgsFile

## Includes

    #include <ags/file/ags_file.h>

## Description

The AgsFile is an object to read or write files using XML. It is the persisting layer of Advanced Gtk+ Sequencer.

The application encoding used is either C.UTF-8 or taken from LANG environment variable.

The following functions convert between encoding and app_encoding:

- ags_file_xml_new_doc()

- ags_file_xml_new_node()

- ags_file_xml_get_prop()

- ags_file_xml_set_prop()

- ags_file_xml_get_content()

- ags_file_xml_set_content()

## Functions

### AGS_FILE_GET_OBJ_MUTEX()

    #define AGS_FILE_GET_OBJ_MUTEX(obj) (&(((AgsFile *) obj)->obj_mutex))

### ags_file_set_filename ()

    void
    ags_file_set_filename (AgsFile *file,
                           gchar *filename);

Set `filename` of `file` .

#### Parameters

file | the AgsFile |
filename | the filename |

Since: 3.6.17

### ags_file_get_filename ()

    gchar *
    ags_file_get_filename (AgsFile *file);

Get filename of `file` .

#### Parameters

file | the AgsFile |

#### Returns

the filename.

[transfer full]

Since: 3.6.17

### ags_file_set_encoding ()

    void
    ags_file_set_encoding (AgsFile *file,
                           gchar *encoding);

Set `encoding` of `file` .

#### Parameters

file | the AgsFile |
encoding | the encoding |

Since: 3.6.17

### ags_file_get_encoding ()

    gchar *
    ags_file_get_encoding (AgsFile *file);

Get encoding of `file` .

#### Parameters

file | the AgsFile |

#### Returns

the encoding.

[transfer full]

Since: 3.6.17

### ags_file_set_audio_format ()

    void
    ags_file_set_audio_format (AgsFile *file,
                               gchar *audio_format);

Set `audio_format` of `file` .

#### Parameters

file | the AgsFile |
audio_format | the audio format |

Since: 3.6.17

### ags_file_get_audio_format ()

    gchar *
    ags_file_get_audio_format (AgsFile *file);

Get audio format of `file` .

#### Parameters

file | the AgsFile |

#### Returns

the audio format.

[transfer full]

Since: 3.6.17

### ags_file_set_audio_encoding ()

    void
    ags_file_set_audio_encoding (AgsFile *file,
                                 gchar *audio_encoding);

Set `audio_encoding` of `file` .

#### Parameters

file | the AgsFile |
audio_encoding | the audio encoding |

Since: 3.6.17

### ags_file_get_audio_encoding ()

    gchar *
    ags_file_get_audio_encoding (AgsFile *file);

Get audio encoding of `file` .

#### Parameters

file | the AgsFile |

#### Returns

the audio encoding.

[transfer full]

Since: 3.6.17

### ags_file_set_xml_doc ()

    void
    ags_file_set_xml_doc (AgsFile *file,
                          xmlDoc *xml_doc);

Set `xml_doc` of `file` .

#### Parameters

file | the AgsFile |
xml_doc | the xmlDoc. | [transfer full]

Since: 3.6.17

### ags_file_get_xml_doc ()

    xmlDoc *
    ags_file_get_xml_doc (AgsFile *file);

Get xml doc of `file` .

#### Parameters

file | the AgsFile |

#### Returns

the xmlDoc.

[transfer none]

Since: 3.6.17

### ags_file_str2md5 ()

    gchar *
    ags_file_str2md5 (gchar *content,
                      guint content_length);

Compute MD5 sums of a buffer.

#### Parameters

content | the string buffer |
content_length | the length of the string |

#### Returns

the md5 checksum.

[transfer full]

Since: 3.0.0

### ags_file_add_id_ref ()

    void
    ags_file_add_id_ref (AgsFile *file,
                         GObject *id_ref);

Adds `id_ref` to `file` .

#### Parameters

file | the `AgsFile` |
id_ref | a reference |

Since: 3.0.0

### ags_file_find_id_ref_by_node ()

    GObject *
    ags_file_find_id_ref_by_node (AgsFile *file,
                                  xmlNode *node);

Find a reference by its XML node.

#### Parameters

file | the `AgsFile` |
node | a XML node |

#### Returns

the matching GObject.

[transfer full]

Since: 3.0.0

### ags_file_find_id_ref_by_xpath ()

    GObject *
    ags_file_find_id_ref_by_xpath (AgsFile *file,
                                   gchar *xpath);

Lookup a reference by `xpath` .

#### Parameters

file | the AgsFile |
xpath | a XPath expression |

#### Returns

the matching GObject.

[transfer full]

Since: 3.0.0

### ags_file_find_id_ref_by_reference ()

    GObject *
    ags_file_find_id_ref_by_reference (AgsFile *file,
                                       gpointer ref);

Find a reference matching `ref` .

#### Parameters

file | the AgsFile |
ref | a `gpointer` |

#### Returns

the matching GObject.

[transfer full]

Since: 3.0.0

### ags_file_add_lookup ()

    void
    ags_file_add_lookup (AgsFile *file,
                         GObject *file_lookup);

Add `file_lookup` for later invoking.

#### Parameters

file | the AgsFile |
file_lookup | a AgsFileLookup |

Since: 3.0.0

### ags_file_add_launch ()

    void
    ags_file_add_launch (AgsFile *file,
                         GObject *file_launch);

Add `file_launch` for later invoking.

#### Parameters

file | the AgsFile |
file_launch | a AgsFileLaunch |

Since: 3.0.0

### ags_file_xml_new_doc ()

    xmlDoc *
    ags_file_xml_new_doc (AgsFile *file,
                          gchar *version);

Create xmlDoc.

#### Parameters

file | the AgsFile |
version | the version |

#### Returns

the newly created xmlDoc.

[transfer full]

Since: 4.0.0

### ags_file_xml_new_node ()

    xmlNode *
    ags_file_xml_new_node (AgsFile *file,
                           xmlNs *xml_namespace,
                           gchar *node_name);

Create xmlNode.

#### Parameters

file | the AgsFile |
xml_namespace | the XML namespace |
node_name | the XML node name |

#### Returns

the newly created xmlNode.

[transfer full]

Since: 4.0.0

### ags_file_xml_get_root_element ()

    xmlNode *
    ags_file_xml_get_root_element (AgsFile *file,
                                   xmlDoc *doc);

Get root element of `doc` .

#### Parameters

file | the AgsFile |
doc | the xmlDoc |

#### Returns

the root element of xmlDoc.

[transfer none]

Since: 4.0.0

### ags_file_xml_set_root_element ()

    void
    ags_file_xml_set_root_element (AgsFile *file,
                                   xmlDoc *doc,
                                   xmlNode *root_node);

Set root element `root_node` of `doc` .

#### Parameters

file | the AgsFile |
doc | the xmlDoc |
root_node | the xmlNode as root node. | [transfer full]

Since: 4.0.0

### ags_file_xml_add_child ()

    void
    ags_file_xml_add_child (AgsFile *file,
                            xmlNode *parent,
                            xmlNode *child);

Set root element `root_node` of `doc` .

#### Parameters

file | the AgsFile |
parent | the parent xmlNode |
child | the child xmlNode. | [transfer full]

Since: 4.0.0

### ags_file_xml_get_node_name ()

    gchar *
    ags_file_xml_get_node_name (AgsFile *file,
                                xmlNode *node);

Get node name of `node` .

#### Parameters

file | the AgsFile |
node | the xmlNode |

#### Returns

the node name of xmlNode.

[transfer full]

Since: 4.0.0

### ags_file_xml_get_node_parent ()

    xmlNode *
    ags_file_xml_get_node_parent (AgsFile *file,
                                  xmlNode *node);

### ags_file_xml_get_node_next ()

    xmlNode *
    ags_file_xml_get_node_next (AgsFile *file,
                                xmlNode *node);

### ags_file_xml_get_node_children ()

    xmlNode *
    ags_file_xml_get_node_children (AgsFile *file,
                                    xmlNode *node);

### ags_file_xml_get_prop ()

    gchar *
    ags_file_xml_get_prop (AgsFile *file,
                           xmlNode *node,
                           gchar *prop_name);

Get property of `node` .

#### Parameters

file | the AgsFile |
node | the xmlNode |
prop_name | property name |

#### Returns

the property of xmlNode.

[transfer full]

Since: 4.0.0

### ags_file_xml_set_prop ()

    void
    ags_file_xml_set_prop (AgsFile *file,
                           xmlNode *node,
                           gchar *prop_name,
                           gchar *prop_value);

Set property of `node` .

#### Parameters

file | the AgsFile |
node | the xmlNode |
prop_name | property name |
prop_value | property value |

Since: 4.0.0

### ags_file_xml_get_content ()

    gchar *
    ags_file_xml_get_content (AgsFile *file,
                              xmlNode *node);

Get content of `node` .

#### Parameters

file | the AgsFile |
node | the xmlNode |

#### Returns

the content of xmlNode.

[transfer full]

Since: 4.0.0

### ags_file_xml_set_content ()

    void
    ags_file_xml_set_content (AgsFile *file,
                              xmlNode *node,
                              gchar *content,
                              gboolean is_cdata);

Set content of `node` .

#### Parameters

file | the AgsFile |
node | the xmlNode |
content | the content |
is_cdata | if content is CDATA |

Since: 4.0.0

### ags_file_open ()

    void
    ags_file_open (AgsFile *file,
                   GError **error);

Opens the file specified by :filename property.

#### Parameters

file | the AgsFile |
error | the return location for errors |

Since: 3.0.0

### ags_file_open_from_data ()

    void
    ags_file_open_from_data (AgsFile *file,
                             gchar *data,
                             guint length,
                             GError **error);

Opens the file provided by `data` .

#### Parameters

file | the AgsFile |
data | a buffer containing the XML document |
length | the buffer length |
error | the return location for errors |

Since: 3.0.0

### ags_file_rw_open ()

    void
    ags_file_rw_open (AgsFile *file,
                      gboolean create,
                      GError **error);

Opens the file specified by :filename property in read-write mode.

#### Parameters

file | the AgsFile |
create | if `TRUE` create the file as needed |
error | the return location for errors |

Since: 3.0.0

### ags_file_open_filename ()

    void
    ags_file_open_filename (AgsFile *file,
                            gchar *filename);

Opens the file specified by `filename` property.

#### Parameters

file | the AgsFile |
filename | a path |

Since: 3.0.0

### ags_file_close ()

    void
    ags_file_close (AgsFile *file);

Closes `file` .

#### Parameters

file | the AgsFile |

Since: 3.0.0

### ags_file_write ()

    void
    ags_file_write (AgsFile *file);

Write the XML document to disk.

#### Parameters

file | the AgsFile |

Since: 3.0.0

### ags_file_write_concurrent ()

    void
    ags_file_write_concurrent (AgsFile *file);

### ags_file_write_resolve ()

    void
    ags_file_write_resolve (AgsFile *file);

Resolve references to XPath expressions.

#### Parameters

file | the AgsFile |

Since: 3.0.0

### ags_file_read ()

    void
    ags_file_read (AgsFile *file);

Read XML document from disk.

#### Parameters

file | the AgsFile |

Since: 3.0.0

### ags_file_read_resolve ()

    void
    ags_file_read_resolve (AgsFile *file);

### ags_file_read_start ()

    void
    ags_file_read_start (AgsFile *file);

Update or start the application.

#### Parameters

file | the AgsFile |

Since: 3.0.0

### ags_file_read_config ()

    void
    ags_file_read_config (AgsFile *file,
                          xmlNode *node,
                          GObject **ags_config);

### ags_file_write_config ()

    void
    ags_file_write_config (AgsFile *file,
                           xmlNode *parent,
                           GObject *ags_config);

### ags_file_read_application_context ()

    void
    ags_file_read_application_context (AgsFile *file,
                                       xmlNode *node,
                                       GObject **application_context);

### ags_file_write_application_context ()

    void
    ags_file_write_application_context (AgsFile *file,
                                        xmlNode *parent,
                                        GObject *application_context);

### ags_file_new ()

    AgsFile *
    ags_file_new ();

Creates an AgsFile

#### Returns

a new AgsFile

Since: 3.0.0

## Types and Values

### AGS_FILE_DEFAULT_APP_ENCODING

    #define AGS_FILE_DEFAULT_APP_ENCODING "C.UTF-8"

### AGS_FILE_DEFAULT_ENCODING

    #define AGS_FILE_DEFAULT_ENCODING "UTF-8"

### AGS_FILE_DEFAULT_DTD

    #define AGS_FILE_DEFAULT_DTD "ags_file.dtd"

### AGS_FILE_CHECKSUM_LENGTH

    #define AGS_FILE_CHECKSUM_LENGTH (32)

### AGS_FILE_DEFAULT_AUDIO_FORMAT

    #define AGS_FILE_DEFAULT_AUDIO_FORMAT "raw"

### AGS_FILE_DEFAULT_AUDIO_ENCODING

    #define AGS_FILE_DEFAULT_AUDIO_ENCODING "base64"

### AGS_FILE_CHARSET_CONVERTER_MAX_STRING_LENGTH

    #define AGS_FILE_CHARSET_CONVERTER_MAX_STRING_LENGTH (8192)

### AGS_FILE_CHARSET_CONVERTER_MAX_CONTENT_LENGTH

    #define AGS_FILE_CHARSET_CONVERTER_MAX_CONTENT_LENGTH (8388608) // max 8 MB

### enum AgsFileFlags

Enum values to control the behavior or indicate internal state of AgsFile by enable/disable as flags.

#### Members

AGS_FILE_READ | opened file for reading |
AGS_FILE_READ_AUDIO_SIGNAL | read audio signal |
AGS_FILE_READ_EMBEDDED_AUDIO | read embedded audio data |
AGS_FILE_WRITE | opened file for writing |
AGS_FILE_WRITE_AUDIO_SIGNAL | write audio signal |
AGS_FILE_WRITE_EMBEDDED_AUDIO | write embedded audio data |

### AGS_FILE_ERROR

    #define AGS_FILE_ERROR (ags_file_error_quark())

### enum AgsFileError

Enum values to indicated failures to used with GError.

#### Members

AGS_FILE_ERROR_PARSER_FAILURE | the parser failed |

## Property Details

### The `“audio-encoding”` property

      “audio-encoding”           char *

The encoding to use for embedding audio data.

Owner: AgsFile

Flags: Read / Write

Default value: "base64"

Since: 3.0.0

### The `“audio-format”` property

      “audio-format”             char *

The format of embedded audio data.

Owner: AgsFile

Flags: Read / Write

Default value: "raw"

Since: 3.0.0

### The `“encoding”` property

      “encoding”                 char *

The charset encoding to use.

Owner: AgsFile

Flags: Read / Write

Default value: NULL

Since: 3.0.0

### The `“filename”` property

      “filename”                 char *

The assigned filename to open and read from.

Owner: AgsFile

Flags: Read / Write

Default value: NULL

Since: 3.0.0

### The `“xml-doc”` property

      “xml-doc”                  gpointer

The assigned xml-doc.

Owner: AgsFile

Flags: Read / Write

Since: 3.0.0

## Signal Details

### The `“open”` signal

    void
    user_function (AgsFile *file,
                   gpointer error,
                   gpointer user_data)

Open `file` with appropriate filename.

#### Parameters

file | the AgsFile |
error | a GError pointer to return error |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 3.0.0

### The `“open-from-data”` signal

    void
    user_function (AgsFile *file,
                   char    *data,
                   guint    length,
                   gpointer error,
                   gpointer user_data)

Open `file` from a buffer containing the file.

#### Parameters

file | the AgsFile |
data | the buffer containing the file |
length | the buffer length |
error | a GError pointer to return error |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 3.0.0

### The `“read”` signal

    void
    user_function (AgsFile *file,
                   gpointer user_data)

Read a XML document from disk with specified filename.

#### Parameters

file | the AgsFile |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 3.0.0

### The `“read-resolve”` signal

    void
    user_function (AgsFile *file,
                   gpointer user_data)

Resolve XPath expressions to their counterpart the newly created instances refering to.

#### Parameters

file | the AgsFile |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 3.0.0

### The `“read-start”` signal

    void
    user_function (AgsFile *file,
                   gpointer user_data)

Hook after reading XML document to update or start the application.

#### Parameters

file | the AgsFile |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 3.0.0

### The `“rw-open”` signal

    void
    user_function (AgsFile *agsfile,
                   gboolean arg1,
                   gpointer arg2,
                   gpointer user_data)

Flags: Run Last

### The `“write”` signal

    void
    user_function (AgsFile *file,
                   gpointer user_data)

Write XML Document to disk.

#### Parameters

file | the AgsFile |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 3.0.0

### The `“write-concurrent”` signal

    void
    user_function (AgsFile *agsfile,
                   gpointer user_data)

Flags: Run Last

### The `“write-resolve”` signal

    void
    user_function (AgsFile *file,
                   gpointer user_data)

Resolve references and generate thus XPath expressions just before writing to disk.

#### Parameters

file | the AgsFile |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 3.0.0