krähemann.com

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 ()
#define AGS_FILE()
#define AGS_FILE_CLASS()
#define AGS_FILE_GET_CLASS()
#define AGS_IS_FILE()
#define AGS_IS_FILE_CLASS()
GType ags_file_flags_get_type ()
GType ags_file_get_type ()

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

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


AGS_FILE()

#define AGS_FILE(obj)                (G_TYPE_CHECK_INSTANCE_CAST((obj), AGS_TYPE_FILE, AgsFile))

AGS_FILE_CLASS()

#define AGS_FILE_CLASS(class)        (G_TYPE_CHECK_CLASS_CAST((class), AGS_TYPE_FILE, AgsFileClass))

AGS_FILE_GET_CLASS()

#define AGS_FILE_GET_CLASS(obj)      (G_TYPE_INSTANCE_GET_CLASS ((obj), AGS_TYPE_FILE, AgsFileClass))

AGS_IS_FILE()

#define AGS_IS_FILE(obj)             (G_TYPE_CHECK_INSTANCE_TYPE ((obj), AGS_TYPE_FILE))

AGS_IS_FILE_CLASS()

#define AGS_IS_FILE_CLASS(class)     (G_TYPE_CHECK_CLASS_TYPE ((class), AGS_TYPE_FILE))

ags_file_flags_get_type ()

GType
ags_file_flags_get_type ();

ags_file_get_type ()

GType
ags_file_get_type (void);

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

 

AGS_TYPE_FILE

#define AGS_TYPE_FILE                (ags_file_get_type())

AGS_TYPE_FILE_FLAGS

#define AGS_TYPE_FILE_FLAGS          (ags_file_flags_get_type())

struct AgsFile

struct AgsFile;

struct AgsFileClass

struct AgsFileClass {
  GObjectClass gobject;

  void (*open)(AgsFile *file,
	       GError **error);
  void (*open_from_data)(AgsFile *file,
			 gchar *data, guint length,
			 GError **error);
  void (*rw_open)(AgsFile *file,
		  gboolean create,
		  GError **error);

  void (*write)(AgsFile *file);
  void (*write_concurrent)(AgsFile *file);
  void (*write_resolve)(AgsFile *file);

  void (*read)(AgsFile *file);
  void (*read_resolve)(AgsFile *file);
  void (*read_start)(AgsFile *file);
};

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