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_drcdar_drc_parse_xml_file (const char *filename, const char *dtdfilepath, dar_sup_exception *exception)
 Parses dar run configuration from xml file.

DLLIMPORT dar_drcdar_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_drcdar_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_specdar_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_storagedar_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_flagsdar_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_archivedar_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.