Main Page Modules Data Structures File List Data Fields Globals

libdrc.h File Reference

Dar run configuration file interpreter library. More...

#include "libdarc.h"

Go to the source code of this file.

Functions

DLLIMPORT dar_drc * dar_drc_parse_xml_file (const char *filename, const char *dtdfilepath, dar_sup_exception *exception)

Parses dar run configuration from xml file.

DLLIMPORT dar_drc * dar_drc_parse_xml_memory (const char *buffer, int size, const char *dtdfilepath, dar_sup_exception *exception)

Parses dar run configuration from memory buffer.

DLLIMPORT bool dar_drc_write_xml_file (const char *filename, dar_sup_exception *exception)

Writes dar run configuration to file.

DLLIMPORT char * dar_drc_write_xml_memory (dar_sup_exception *exception)

Writes dar run configuration to newly assigned memory buffer.

DLLIMPORT dar_drc * dar_drc_create (dar_drc *reference, dar_sup_spec *spec, dar_sup_storage *storage, dar_sup_flags *flags)

Creates a drc object from archive description structures.

DLLIMPORT dar_sup_spec * dar_drc_get_spec (dar_drc *ref)

Retrieves a pointer to the dar_sup_spec structure describing the archive in a drc object.

DLLIMPORT dar_sup_storage * dar_drc_get_storage (dar_drc *ref)

Retrieves a pointer to the dar_sup_storage structure describing the archive in a drc object.

DLLIMPORT dar_sup_flags * dar_drc_get_flags (dar_drc *ref)

Retrieves a pointer to the dar_sup_flags structure describing the archive in a drc object.

DLLIMPORT char * dar_drc_get_passphrase (dar_drc *ref)

Retrieves stored passphrase from archive specification.

DLLIMPORT bool dar_drc_set_passphrase (dar_drc *ref, char *passphrase)

Replaces stored passphrase in the archive specification.

DLLIMPORT bool dar_drc_has_reference (dar_drc *ref)

Determines if a given drc object contains a reference archive specification.

DLLIMPORT dar_archive * dar_drc_open_reference (dar_user_interaction_struct dialog, dar_drc *ref, dar_sup_exception *exception)

Opens a reference archive from a stored specification.

DLLIMPORT char * dar_drc_get_reference_passphrase (dar_drc *ref)

Retrieves stored passphrase from reference archive specification.

DLLIMPORT bool dar_drc_set_reference_passphrase (dar_drc *ref, char *passphrase)

Replaces stored passphrase in the archive specification.

DLLIMPORT void dar_drc_destroy (dar_drc *ref)

Frees all memory for the drc object and the elements it contains.

Detailed Description

Dar run configuration file interpreter library.

Provides tools to parse Xml drc files.

Definition in file libdrc.h.

Function Documentation

DLLIMPORT dar_drc* dar_drc_create ( dar_drc * reference,

dar_sup_spec * spec,

dar_sup_storage * storage,

dar_sup_flags * flags

)

Creates a drc object from archive description structures.
This function takes pointers to support structures. These structures will not be copied. Instead, the pointers will be stored directly in the drc object. Therefore, the structures must be allocated on the heap and must not be freed by the caller directly. They will be free and destroyed when dar_drc_destroy is called.
Parameters:

reference A drc object containing a description of an archive that will be used as a reference to the new archive. This should be null if no reference should be used.

spec Archive options structure. Will be freed by drc library when dar_drc_destroy is called, but may be used by caller until then.

storage Archive storage structure. Will be freed by drc library when dar_drc_destroy is called, but may be used by caller until then.

flags Options flags structure. Will be freed by drc library when dar_drc_destroy is called, but may be used by caller until then.

Returns:
A new drc object. null indicates memory exhaustion.

Definition at line 257 of file libdrc.c.
References dar_drc_destroy().

DLLIMPORT void dar_drc_destroy ( dar_drc * ref )

Frees all memory for the drc object and the elements it contains.
All internal specification and support objects will be freed, so this function must not be called while dar_sup structs are being used.
Definition at line 208 of file libdrc.c.
References dar_sup_spec_destroy(), and dar_sup_storage_destroy().
Referenced by dar_drc_create(), dar_drc_parse_xml_file(), and dar_drc_parse_xml_memory().

DLLIMPORT dar_sup_flags* dar_drc_get_flags ( dar_drc * ref )

Retrieves a pointer to the dar_sup_flags structure describing the archive in a drc object.
The dar_sup_flags structure will be freed when dar_drc_destroy is called. All operations involving the structure must be completed before the drc object is freed.
Definition at line 202 of file libdrc.c.

DLLIMPORT char* dar_drc_get_passphrase ( dar_drc * ref )

Retrieves stored passphrase from archive specification.
In some cases, it may be desirable to store a passphrase in a drc file. This can be valuable when creating session keys, which can then be encrypted before final storage.
This function should be used to directly retrieve a copy of a passphrase in whatever form it is currently stored.
Parameters:

ref Drc object containing archive specification.

Returns:
String containing passphrase in its currently stored form. This string must be freed by the caller. This will be null if there is no password stored.

Definition at line 106 of file libdrc.c.

DLLIMPORT char* dar_drc_get_reference_passphrase ( dar_drc * ref )

Retrieves stored passphrase from reference archive specification.
This is the counterpart to dar_drc_get_passphrase for use with a reference archive.
Parameters:

ref Drc object containing archive specification.

Returns:
String containing passphrase in its currently stored form. This string must be freed by the caller. This will be null if there is no password stored or there is no reference archive.

Definition at line 133 of file libdrc.c.

DLLIMPORT dar_sup_spec* dar_drc_get_spec ( dar_drc * ref )

Retrieves a pointer to the dar_sup_spec structure describing the archive in a drc object.
The dar_sup_spec structure will be freed when dar_drc_destroy is called. All operations involving the structure must be completed before the drc object is freed.
Definition at line 190 of file libdrc.c.

DLLIMPORT dar_sup_storage* dar_drc_get_storage ( dar_drc * ref )

Retrieves a pointer to the dar_sup_storage structure describing the archive in a drc object.
The dar_sup_storage structure will be freed when dar_drc_destroy is called. All operations involving the structure must be completed before the drc object is freed.
Definition at line 196 of file libdrc.c.

DLLIMPORT bool dar_drc_has_reference ( dar_drc * ref )

Determines if a given drc object contains a reference archive specification.
Any archive opened from a drc file may be based on a reference archive. This function can be used to determine if a given archive stored in a drc object depends on a reference archive. That archive must be opened with dar_drc_open_reference before some archive operations.
Parameters:

ref Drc object to check for a reference archive.

Returns:
true if a reference archive is present; otherwise false.

Definition at line 160 of file libdrc.c.

DLLIMPORT dar_archive* dar_drc_open_reference ( dar_user_interaction_struct dialog,

dar_drc * ref,

dar_sup_exception * exception

)

Opens a reference archive from a stored specification.
Any archive opened from a drc file may be based on a reference archive. When an archive operation requires access to that reference archive, this function can be used to open that archive.
Parameters:

ref Drc object containing a reference archive.

exception Exception type container. This should be an empty container. Any unfreed pointers may be lost.

Returns:
An archive object containing the opened reference archive.

Definition at line 166 of file libdrc.c.
References dar_op_archive_open(), LIBDAR_NOEXCEPT, and dar_sup_exception::type.

DLLIMPORT dar_drc* dar_drc_parse_xml_file ( const char * filename,

const char * dtdfilepath,

dar_sup_exception * exception

)

Parses dar run configuration from xml file.
All strings will be copied, originals must be freed by caller.
Parameters:

filename Relative or absolute path to xml drc file.

dtdfilepath Relative or absolute path to a special dtd; otherwise the default dtd is used.

exception Exception type container. This should be an empty container. Any unfreed pointers may be lost.

Returns:
A new drc object containing archive specifications and status information; null if drc file could not be parsed or another exception occured.

Definition at line 487 of file libdrc.c.
References dar_drc_destroy(), LIBDAR_EMEMORY, LIBDAR_NOEXCEPT, LIBDAR_X_EINPUTSPEC, LIBDARC_EXCEPTION, and dar_sup_exception::type.

DLLIMPORT dar_drc* dar_drc_parse_xml_memory ( const char * buffer,

int size,

const char * dtdfilepath,

dar_sup_exception * exception

)

Parses dar run configuration from memory buffer.
All strings will be copied, originals must be freed by caller.
Parameters:

buffer Memory containing UTF-8 encoded xml drc file.

dtdfilepath Relative or absolute path to a special dtd; otherwise the default dtd is used.

exception Exception type container. This should be an empty container. Any unfreed pointers may be lost.

Returns:
A new drc object containing archive specifications a status information; null if drc file could not be parsed or another exception occured.

Definition at line 408 of file libdrc.c.
References dar_drc_destroy(), LIBDAR_EMEMORY, LIBDAR_NOEXCEPT, LIBDAR_X_EINPUTSPEC, LIBDARC_EXCEPTION, and dar_sup_exception::type.

DLLIMPORT bool dar_drc_set_passphrase ( dar_drc * ref,

char * passphrase

)

Replaces stored passphrase in the archive specification.
In some cases, it may be desirable to store a passphrase in a drc file. This can be valuable when creating session keys, which can then be encrypted before final storage.
This function should be used to directly replace a copy of a passphrase to an encrypted or decrypted form.
Parameters:

ref Drc object containing archive specification.

passphrase String containing passphrase in new form. This string will be copied; original must be freed by the caller.

Returns:
true if copied successfully; false on memory error.

Definition at line 117 of file libdrc.c.

DLLIMPORT bool dar_drc_set_reference_passphrase ( dar_drc * ref,

char * passphrase

)

Replaces stored passphrase in the archive specification.
This is the counterpart to dar_drc_set_passphrase for use with a reference archive.
Parameters:

ref Drc object containing archive specification.

passphrase String containing passphrase in new form. This string will be copied; original must be freed by the caller. No action will be performed if there is no reference archive.

Definition at line 144 of file libdrc.c.

DLLIMPORT bool dar_drc_write_xml_file ( const char * filename,

dar_sup_exception * exception

)

Writes dar run configuration to file.

Parameters:

filename Relative or absolute path to target xml drc file.

exception Exception type container. This should be an empty container. Any unfreed pointers may be lost.

Returns:
true on success; otherwise false.

Definition at line 388 of file libdrc.c.
References LIBDAR_ELIBCALL, and LIBDARC_EXCEPTION.


Functions
DLLIMPORT dar_drc *	dar_drc_parse_xml_file (const char filename, const char dtdfilepath, dar_sup_exception *exception)
	Parses dar run configuration from xml file.
DLLIMPORT dar_drc *	dar_drc_parse_xml_memory (const char buffer, int size, const char dtdfilepath, dar_sup_exception *exception)
	Parses dar run configuration from memory buffer.
DLLIMPORT bool	dar_drc_write_xml_file (const char filename, dar_sup_exception exception)
	Writes dar run configuration to file.
DLLIMPORT char *	dar_drc_write_xml_memory (dar_sup_exception *exception)
	Writes dar run configuration to newly assigned memory buffer.
DLLIMPORT dar_drc *	dar_drc_create (dar_drc reference, dar_sup_spec spec, dar_sup_storage storage, dar_sup_flags flags)
	Creates a drc object from archive description structures.
DLLIMPORT dar_sup_spec *	dar_drc_get_spec (dar_drc *ref)
	Retrieves a pointer to the `dar_sup_spec` structure describing the archive in a drc object.
DLLIMPORT dar_sup_storage *	dar_drc_get_storage (dar_drc *ref)
	Retrieves a pointer to the `dar_sup_storage` structure describing the archive in a drc object.
DLLIMPORT dar_sup_flags *	dar_drc_get_flags (dar_drc *ref)
	Retrieves a pointer to the `dar_sup_flags` structure describing the archive in a drc object.
DLLIMPORT char *	dar_drc_get_passphrase (dar_drc *ref)
	Retrieves stored passphrase from archive specification.
DLLIMPORT bool	dar_drc_set_passphrase (dar_drc ref, char passphrase)
	Replaces stored passphrase in the archive specification.
DLLIMPORT bool	dar_drc_has_reference (dar_drc *ref)
	Determines if a given drc object contains a reference archive specification.
DLLIMPORT dar_archive *	dar_drc_open_reference (dar_user_interaction_struct dialog, dar_drc ref, dar_sup_exception exception)
	Opens a reference archive from a stored specification.
DLLIMPORT char *	dar_drc_get_reference_passphrase (dar_drc *ref)
	Retrieves stored passphrase from reference archive specification.
DLLIMPORT bool	dar_drc_set_reference_passphrase (dar_drc ref, char passphrase)
	Replaces stored passphrase in the archive specification.
DLLIMPORT void	dar_drc_destroy (dar_drc *ref)
	Frees all memory for the drc object and the elements it contains.