1LIBDATOVKA(3) Manual for Libdatovka LIBDATOVKA(3)
2
6 libdatovka - ISDS client library
7
9 #include <libdatovka/isds.h>
10 #include <stdio.h>
11 isds_error err;
13 struct isds_ctx *ctx;
14 err = isds_init();
16 ctx = isds_ctx_create();
17 err = isds_login(ctx, NULL, "username", "password", NULL, NULL);
19 if (err) {
20 printf("isds_login() failed: %s: %s\n",
21 isds_strerror(err), isds_long_message(ctx));
22 } else {
23 printf("Logged in.\n");
24 }
25 err = isds_ctx_free(&ctx);
27 err = isds_cleanup();
28
30 This is a client library for accessing SOAP services of ISDS (In‐
31 formační systém datových schránek / Data Box Information System) as de‐
32 fined in Czech ISDS Act (300/2008 Coll.)[1] and implied documents. Cur‐
33 rent implementation details are described in Provozní řád that can be
34 downloaded from Dokumenty ke stažení section of ISDS Information
35 Portal[2].
36 The library provides a C language interface with synchronous non-reen‐
38 trant blocking calls. Network communication progress reporting and op‐
39 eration logging and library debugging are implemented by calling back
40 application-provided functions. Network operations can be cancelled
41 from network reporting call-back.
42
44 A libdatovka application must include the libdatovka/isds.h header
45 file. The application must call isds_init function to initialize the
46 library before calling any other library functions. After last libda‐
47 tovka call, isds_cleanup function should be called to clean up some
48 global resources and to deinitialize dependent libraries.
49
51 Most of the functions operate on an established connection to the ISDS
52 server. This is called a context and it's represented by a pointer to
53 an opaque isds_ctx structure. The structure maintains state about net‐
54 work connection, authorization or error from last call on the context.
55 The context is allocated by isds_ctx_create function and deallocated by
57 isds_ctx_free function.
58 There are more context subtypes. A specific subtype is assigned to the
60 context when a fresh new context is passed to one of the few stratify‐
61 ing functions (isds_login, czp_convert_document,
62 isds_request_new_testing_box). Once the context is specialized, you can
63 use it only with functions understanding the subtype. This is not en‐
64 forced by the library now, but it does not matter much because all the
65 other functions assume the isds_login was called on the context. In
66 other words, do not share the context among the three stratifying func‐
67 tions.
68 For example create a context with isds_ctx_create, then call
70 isds_login, then work with box, then call isds_logout. Here you can re‐
71 use the context and log in as another user by calling isds_login again
72 or destroy the context with isds_ctx_free if you don't need it anymore.
73 Or create a context with isds_ctx_create, send a document to authorized
75 conversion using czp_convert_document, then you can send more documents
76 to the authorized conversion by calling czp_convert_document again on
77 the same context and finally destroy the context with isds_ctx_free.
78
80 Most of the functions return an error code of isds_error type. IE_SUC‐
81 CESS value denotes a successful call. Other values represent some kind
82 of failure.
83 You can use isds_strerror function to obtain a human readable string
85 representation of the error code.
86 If a function with context argument failed, you can use
88 isds_long_message function to obtain a detailed error message. Please
89 note that returned value lasts only to the next call on the context.
90
92 All strings exchanged between the library and the application are en‐
93 coded in UTF-8. Although there are a few exceptions:
94 • isds_strerror and isds_long_message functions return locale encoded
96 string.
97 • isds_version returns locale encoded string.
99 • Log call-back function set by isds_set_log_callback function is
101 called with raw byte stream.
102 • isds_pki_credentials structure string members have encoding spe‐
104 cific to cryptographic library linked to cURL library.
105
107 Some functions influence library behaviour globally. These are:
108 • isds_init and isds_cleanup used to initialize and deinitialize the
110 library.
111 • isds_set_logging and isds_set_log_callback to set logging.
113
115 Logging is global for all libdatovka calls. Log level and facility can
116 be set with isds_set_logging function.
117 The log is printed on standard error output by default. Application can
119 redirect the messages to a call-back function by registering the
120 call-back function with isds_set_log_callback.
121
123 Some functions operating on a context create network sockets and do
124 network input and output.
125 Network timeout can be set with isds_set_timeout function. Function
127 calls aborted owing to the timeout will return IE_TIMED_OUT.
128 Network operation progress can be monitored by a call-back function.
130 The call-back function can be registered using
131 isds_set_progress_callback function. Registered call-back function will
132 be called periodically with arguments declaring amount of transferred
133 data. The call-back return value determines whether to continue in the
134 network operation or to cancel the operation. Functions failed owing to
135 cancelling network operation will return IE_ABORTED.
136
138 The library provides destructors for all libdatovka data structures.
139 For example isds_ctx_free function accepts a pointer to a pointer to
140 the isds_ctx structure, frees the double referenced structure (recur‐
141 sively), writes NULL to the pointed pointer (which invalidates the
142 pointer effectively) and returns nothing.
143 Upon a function call, all output arguments are automatically reallo‐
145 cated to desired size. On a function failure, all output arguments are
146 automatically deallocated and their pointers set to NULL. Exceptions
147 are documented at respective functions.
148 Output strings are allocated using standard malloc call. Application is
150 responsible for their deallocation (in case of no failure and if not
151 specified otherwise.) Use standard free call for strings, use libda‐
152 tovka destructors for libdatovka structures.
153
155 See libdatovka/isds.h header file.
156
158 isds.h.libdatovka(3), libcurl(3)
159
161 CZ.NIC, z. s. p. o.
162 Maintains libdatovka. Has been contributing to libisds.
163 Petr Písař
165 He has written libisds.
166
168 1. Czech
169 ISDS Act (300/2008 Coll.)
170 http://portal.gov.cz/zakon/300/2008
171 2. Dokumenty ke stažení section of
173 ISDS Information Portal
174 https://www.datoveschranky.info/ke-stazeni
175[FIXME: source] 11/09/2023 LIBDATOVKA(3)