LIBDATOVKA(3) | Manual for Libdatovka | LIBDATOVKA(3) |
.SH "NAME" libdatovka - ISDS client library
.SH "SYNOPSIS"
#include <libdatovka/isds.h> #include <stdio.h> isds_error err; struct isds_ctx *ctx; err = isds_init(); ctx = isds_ctx_create(); err = isds_login(ctx, NULL, "username", "password", NULL, NULL); if (err) { printf("isds_login() failed: %s: %s\n", isds_strerror(err), isds_long_message(ctx)); } else { printf("Logged in.\n"); } err = isds_ctx_free(&ctx); err = isds_cleanup();
.SH "DESCRIPTION"
.PP This is a client library for accessing SOAP services of ISDS
(Informační systém datových
schránek / Data Box Information System) as defined in Czech
ISDS Act (300/2008 Coll.)[1] and implied documents. Current
implementation details are described in Provozní řád
that can be downloaded from Dokumenty ke stažení section of
ISDS Information Portal[2].
.PP The library provides a C language interface with synchronous
non-reentrant blocking calls. Network communication progress reporting and
operation logging and library debugging are implemented by calling back
application-provided functions. Network operations can be cancelled from
network reporting call-back.
.SH "LIBRARY INITIALIZATION AND DEINITIALIZATION"
.PP A libdatovka application must include the libdatovka/isds.h header file.
The application must call isds_init function to initialize the
library before calling any other library functions. After last libdatovka
call, isds_cleanup function should be called to clean up some global
resources and to deinitialize dependent libraries.
.SH "CONTEXTS"
.PP Most of the functions operate on an established connection to the ISDS
server. This is called a context and it's represented by a pointer to an
opaque isds_ctx structure. The structure maintains state about network
connection, authorization or error from last call on the context.
.PP The context is allocated by isds_ctx_create function and
deallocated by isds_ctx_free function.
.PP There are more context subtypes. A specific subtype is assigned to the
context when a fresh new context is passed to one of the few stratifying
functions (isds_login, czp_convert_document,
isds_request_new_testing_box). Once the context is specialized, you
can use it only with functions understanding the subtype. This is not
enforced by the library now, but it does not matter much because all the
other functions assume the isds_login was called on the context. In
other words, do not share the context among the three stratifying
functions.
.PP For example create a context with isds_ctx_create, then call
isds_login, then work with box, then call isds_logout. Here
you can reuse the context and log in as another user by calling
isds_login again or destroy the context with isds_ctx_free if
you don't need it anymore.
.PP Or create a context with isds_ctx_create, send a document to
authorized conversion using czp_convert_document, then you can send
more documents to the authorized conversion by calling
czp_convert_document again on the same context and finally destroy
the context with isds_ctx_free.
.SH "ERRORS"
.PP Most of the functions return an error code of isds_error type.
IE_SUCCESS value denotes a successful call. Other values represent some kind
of failure.
.PP You can use isds_strerror function to obtain a human readable
string representation of the error code.
.PP If a function with context argument failed, you can use
isds_long_message function to obtain a detailed error message. Please
note that returned value lasts only to the next call on the context.
.SH "CHARACTER ENCODING"
.PP All strings exchanged between the library and the application are encoded
in UTF-8. Although there are a few exceptions:
isds_strerror and isds_long_message functions return locale encoded string.
.RE
isds_version returns locale encoded string.
.RE
Log call-back function set by isds_set_log_callback function is called with raw byte stream.
.RE
isds_pki_credentials structure string members have encoding specific to cryptographic library linked to cURL library.
.RE
.SH "GLOBAL SETTINGS"
.PP Some functions influence library behaviour globally. These are:
isds_init and isds_cleanup used to initialize and deinitialize the library.
.RE
isds_set_logging and isds_set_log_callback to set logging.
.RE
.SH "LOGGING AND DEBUGGING"
.PP Logging is global for all libdatovka calls. Log level and facility can be
set with isds_set_logging function.
.PP The log is printed on standard error output by default. Application can
redirect the messages to a call-back function by registering the call-back
function with isds_set_log_callback.
.SH "NETWORK INPUT/OUTPUT"
.PP Some functions operating on a context create network sockets and do
network input and output.
.PP Network timeout can be set with isds_set_timeout function.
Function calls aborted owing to the timeout will return IE_TIMED_OUT.
.PP Network operation progress can be monitored by a call-back function. The
call-back function can be registered using isds_set_xferinfo_callback
function. Registered call-back function will be called periodically with
arguments declaring amount of transferred data. The call-back return value
determines whether to continue in the network operation or to cancel the
operation. Functions failed owing to cancelling network operation will
return IE_ABORTED. The now deprecated call-back function
isds_set_progress_callback behaves similarly but uses floating-point
values to pass amounts of transferred data. Is is discouraged to use
isds_set_progress_callback in new code.
.SH "MEMORY MANAGEMENT"
.PP The library provides destructors for all libdatovka data structures. For
example isds_ctx_free function accepts a pointer to a pointer to the
isds_ctx structure, frees the double referenced structure (recursively),
writes NULL to the pointed pointer (which invalidates the pointer
effectively) and returns nothing.
.PP Upon a function call, all output arguments are automatically reallocated
to desired size. On a function failure, all output arguments are
automatically deallocated and their pointers set to NULL. Exceptions are
documented at respective functions.
.PP Output strings are allocated using standard malloc call.
Application is responsible for their deallocation (in case of no failure and
if not specified otherwise.) Use standard free call for strings, use
libdatovka destructors for libdatovka structures.
.SH "AVAILABLE FUNCTIONS, TYPES, AND CONSTANTS"
.PP See libdatovka/isds.h header file.
.SH "SEE ALSO"
.PP isds.h.libdatovka(3), libcurl(3)
.SH "AUTHORS"
CZ.NIC, z. s. p. o.
Petr Písař
NOTES
- 1.
- Czech
ISDS Act (300/2008 Coll.)
- 2.
- Dokumenty ke stažení section of
ISDS Information Portal
05/11/2024 | [FIXME: source] |