'\" t
.\"     Title: libdatovka
.\"    Author: CZ.NIC, z. s. p. o.
.\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
.\"      Date: 05/11/2024
.\"    Manual: Manual for Libdatovka
.\"    Source: [FIXME: source]
.\"  Language: English
.\"
.TH "LIBDATOVKA" "3" "05/11/2024" "[FIXME: source]" "Manual for Libdatovka"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------

    

    .SH "NAME"
libdatovka \- ISDS client library


    .SH "SYNOPSIS"

      
.sp
.nf
#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\en",
        isds_strerror(err), isds_long_message(ctx));
} else {
    printf("Logged in\&.\en");
}

err = isds_ctx_free(&ctx);
err = isds_cleanup();
.fi
.sp

    

    .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
\m[blue]\fBCzech ISDS Act (300/2008 Coll\&.)\fR\m[]\&\s-2\u[1]\d\s+2
and implied documents\&. Current implementation details are described in
Provozní řád
that can be downloaded from
\m[blue]\fBDokumenty ke stažení section of ISDS Information Portal\fR\m[]\&\s-2\u[2]\d\s+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
\%\fBisds_init\fR
function to initialize the library before calling any other library functions\&. After last libdatovka call,
\%\fBisds_cleanup\fR
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\*(Aqs 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
\%\fBisds_ctx_create\fR
function and deallocated by
\%\fBisds_ctx_free\fR
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 (\%\fBisds_login\fR,
\%\fBczp_convert_document\fR,
\%\fBisds_request_new_testing_box\fR)\&. 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
\%\fBisds_login\fR
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
\%\fBisds_ctx_create\fR, then call
\%\fBisds_login\fR, then work with box, then call
\%\fBisds_logout\fR\&. Here you can reuse the context and log in as another user by calling
\%\fBisds_login\fR
again or destroy the context with
\%\fBisds_ctx_free\fR
if you don\*(Aqt need it anymore\&.


      .PP
Or create a context with
\%\fBisds_ctx_create\fR, send a document to authorized conversion using
\%\fBczp_convert_document\fR, then you can send more documents to the authorized conversion by calling
\%\fBczp_convert_document\fR
again on the same context and finally destroy the context with
\%\fBisds_ctx_free\fR\&.


    

    .SH "ERRORS"

      

      .PP
Most of the functions return an error code of
\%\fBisds_error\fR
type\&.
IE_SUCCESS
value denotes a successful call\&. Other values represent some kind of failure\&.


      .PP
You can use
\%\fBisds_strerror\fR
function to obtain a human readable string representation of the error code\&.


      .PP
If a function with context argument failed, you can use
\%\fBisds_long_message\fR
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:


      
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

          \%\fBisds_strerror\fR
and
\%\fBisds_long_message\fR
functions return locale encoded string\&.

        .RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

          \%\fBisds_version\fR
returns locale encoded string\&.

        .RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

          Log call\-back function set by
\%\fBisds_set_log_callback\fR
function is called with raw byte stream\&.

        .RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

          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:


      
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

          \%\fBisds_init\fR
and
\%\fBisds_cleanup\fR
used to initialize and deinitialize the library\&.

        .RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

          \%\fBisds_set_logging\fR
and
\%\fBisds_set_log_callback\fR
to set logging\&.

        .RE
    

    .SH "LOGGING AND DEBUGGING"

      

      .PP
Logging is global for all libdatovka calls\&. Log level and facility can be set with
\%\fBisds_set_logging\fR
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
\%\fBisds_set_log_callback\fR\&.

    

    .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
\%\fBisds_set_timeout\fR
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
\%\fBisds_set_xferinfo_callback\fR
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
\%\fBisds_set_progress_callback\fR
behaves similarly but uses floating\-point values to pass amounts of transferred data\&. Is is discouraged to use
\%\fBisds_set_progress_callback\fR
in new code\&.

    

    .SH "MEMORY MANAGEMENT"

      

      .PP
The library provides destructors for all libdatovka data structures\&. For example
\%\fBisds_ctx_free\fR
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
\%\fBmalloc\fR
call\&. Application is responsible for their deallocation (in case of no failure and if not specified otherwise\&.) Use standard
\%\fBfree\fR
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
\fBisds.h.libdatovka\fR(3), \fBlibcurl\fR(3)

    
  .SH "AUTHORS"
.PP
\fBCZ.NIC, z. s. p. o.\fR
.RS 4
Maintains libdatovka. Has been contributing to libisds.
.RE
.PP
\fBPetr Písař\fR
.RS 4
He has written libisds.
.RE
.SH "NOTES"
.IP " 1." 4
Czech
          ISDS Act (300/2008 Coll.)
.RS 4
\%\%http://portal.gov.cz/zakon/300/2008
.RE
.IP " 2." 4
Dokumenty ke stažení section of
          ISDS Information Portal
.RS 4
\%\%https://www.datoveschranky.info/ke-stazeni
.RE