1LIBISDS(3)                    Manual for Libisds                    LIBISDS(3)
2
3
4

NAME

6       libisds - ISDS client library
7

SYNOPSIS

9       #include <isds.h>
10       #include <stdio.h>
11
12       isds_error err;
13       struct isds_ctx *ctx;
14
15       err = isds_init();
16       ctx = isds_ctx_create();
17
18       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
26       err = isds_ctx_free(&ctx);
27       err = isds_cleanup();
28

DESCRIPTION

30       This   is  a  client  library  for  accessing  SOAP  services  of  ISDS
31       (Informační systém datových schránek / Data Box Information System)  as
32       defined  in  Czech  ISDS Act (300/2008 Coll.)[1] and implied documents.
33       Current implementation details are described in Provozní řád  that  can
34       be  downloaded  from  Dokumenty  ke stažení section of ISDS Information
35       Portal[2].
36
37       The library provides a C language interface with synchronous  non-reen‐
38       trant  blocking  calls.  Network  communication  progress reporting and
39       operation logging and library debugging are implemented by calling back
40       application-provided functions. Network operations can be canceled from
41       network reporting call-back.
42

LIBRARY INITIALIZATION AND DEINITIALIZATION

44       A libisds application must include isds.h header file. The  application
45       must  call  isds_init function to initialize the library before calling
46       any other library functions.  After  last  libisds  call,  isds_cleanup
47       function  should  be  called  to  clean up some global resources and to
48       deinitialize dependent libraries.
49

CONTEXTS

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
56       The context is allocated by isds_ctx_create function and deallocated by
57       isds_ctx_free function.
58
59       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
64       enforced  by  the  library now, but it does not matter much because all
65       the 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
69       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
74       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

ERRORS

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
84       You can use isds_strerror function to obtain a  human  readable  string
85       representation of the error code.
86
87       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

CHARACTER ENCODING

92       All  strings  exchanged  between  the  library  and the application are
93       encoded in UTF-8. Although there are a few exceptions:
94
95       ·   isds_strerror and isds_long_message functions return locale encoded
96           string.
97
98       ·   isds_version returns locale encoded string.
99
100       ·   Log  call-back  function  set  by isds_set_log_callback function is
101           called with raw byte stream.
102
103       ·   isds_pki_credentials structure string members  have  encoding  spe‐
104           cific to cryptographic library linked to cURL library.
105

GLOBAL SETTINGS

107       Some functions influence library behavior globally. These are:
108
109       ·   isds_init  and isds_cleanup used to initialize and deinitialize the
110           library.
111
112       ·   isds_set_logging and isds_set_log_callback to set logging.
113

LOGGING AND DEBUGGING

115       Logging is global for all libisds calls. Log level and facility can  be
116       set with isds_set_logging function.
117
118       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

NETWORK INPUT/OUTPUT

123       Some  functions  operating  on  a context create network sockets and do
124       network input and output.
125
126       Network timeout can be set  with  isds_set_timeout  function.  Function
127       calls aborted owing to the timeout will return IE_TIMED_OUT.
128
129       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       canceling network operation will return IE_ABORTED.
136

MEMORY MANAGEMENT

138       The  library  provides destructors for all libisds data structures. For
139       example isds_ctx_free function accepts a pointer to a  pointer  to  the
140       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
144       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
149       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  libisds
152       destructors for libisds structures.
153

AVAILABLE FUNCTIONS, TYPES, AND CONSTANTS

155       See isds.h header file.
156

SEE ALSO

158       isds.h(3), libcurl(3)
159

AUTHOR

161       Petr Písař
162           He has written libisds.
163

NOTES

165        1. Czech
166                     ISDS Act (300/2008 Coll.)
167           http://portal.gov.cz/zakon/300/2008
168
169        2. Dokumenty ke stažení section of
170                     ISDS Information Portal
171           https://www.datoveschranky.info/ke-stazeni
172
173
174
175libisds                           09/06/2019                        LIBISDS(3)
Impressum