======libartefact======
=====Introduction=====
Libartefact is a client library that can be used to connect to the [[Artefact]] data server, for data retrieval and insertion.\\
The library takes care of http communication, encryption/decryption (optionally), XML translations and error handling.
It is intended as a complete interface to the communication possibilities with the Artefact server.

=====How to use libartefact=====
To use libartefact, simply include ''libartefact.h'' in your c file.
The project supplies a pkg-config file called libartefact.pc, that should be located in the ''${prefix}/lib/pkgconfig/'', where ''${prefix}'' is the base directory in which the library is installed. This will be ''/usr'' on most systems.
In order to use it simply add 
<code autoconf>
PKG_CHECK_MODULES(ATF, libartefact >= 0.0.2)
</code>
to ''configure.in'', and supply ''ATF_CFLAGS'' to the cflags and ''ATF_LIBS'' to the libs of your project ''Makefile.am''.
Alternatively use the ''pkg-config --libs libartefact'' and ''pkg-config --cflags libartefact'' commands directly in your ''Makefile'' (if not using autotools).

=====API overview=====

<code c>
atf_handle_t *handle = atf_init();
void atf_close(handle);
</code>

=====Error handling=====
<code c>

// ... here should be some code that allocates handle and does something useful ...

atf_error_t err = atf_get_last_error(handle);

if(err != ATF_NO_ERROR) {
  char buf[512];
  printf("Error: %s\n", atf_get_error_string(err, buf, sizeof(buf));
}
</code>

=====Replies=====
When a reply is received, it can either be obtained from the library in its raw form, on in parsed form, where the XML is evaluated and returned in a recursive structure, much like an XML DOM model.
If the result is read in its raw form, the handling of interpretation must be done by the client using the library.
This can be useful if the result contains an image as raw binary data, or the parsed data must fit into some already defined internal structure.
The raw data is simply a verbatim copy of the character data contained within the reply nodes in the server response document. If the data is raw binary data, it will most likely be base64 encoded, which must be handled by the client using the library.
If the raw data is not raw binary data, it will most likely contain a tree of XML nodes, without the header. It is important to note that this XML data cannot be fed directly to a strict XML parser, since it is in itself not a valid XML document. It will however be well balanced. In order to force it to become a valid XML document a single outer (root) element must be added (ex. ''<data>'' and ''</data>''), encapsulating the data. Also a header must be added, containing the following directives: ''<?xml version='1.0' encoding='utf-8'?>''