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.
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
PKG_CHECK_MODULES(ATF, libartefact >= 0.0.2)
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).
atf_handle_t *handle = atf_init(); void atf_close(handle);
// ... 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)); }
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'?>