home | help 
LIBDATOVKA(3)		      Manual for Libdatovka		   LIBDATOVKA(3)

NAME
     libdatovka - ISDS client library

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();

DESCRIPTION
     This  is  a  client library for accessing SOAP services of ISDS (InformaAnA
     systA(C)m datovA1/2ch schrA!nek / Data Box Information System)  as  defined
     in Czech ISDS Act (300/2008 Coll.)[1] and implied documents. Current imple-
     mentation	details  are  described  in ProvoznA AA!d that can be downloaded
     from Dokumenty ke staoA3/4en~A section of ISDS Information Portal[2].

     The library provides a C language interface with synchronous  non-reentrant
     blocking calls. Network communication progress reporting and operation log-
     ging and library debugging are implemented by calling back application-pro-
     vided functions. Network operations can be cancelled from network reporting
     call-back.

LIBRARY INITIALIZATION AND DEINITIALIZATION
     A	libdatovka  application  must include the libdatovka/isds.h header file.
     The application must call isds_init function to initialize the library  be-
     fore  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.

CONTEXTS
     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 con-
     nection, authorization or error from last call on the context.

     The  context  is  allocated  by isds_ctx_create function and deallocated by
     isds_ctx_free function.

     There are more context subtypes. A specific subtype is assigned to the con-
     text when a fresh new context is passed to one of the few stratifying func-
     tions  (isds_login,  czp_convert_document,   isds_request_new_testing_box).
     Once  the context is specialized, you can use it only with functions under-
     standing 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.

     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 con-
     text with isds_ctx_free if you don't need it anymore.

     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.

ERRORS
     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 fail-
     ure.

     You can use isds_strerror function to obtain a human readable string repre-
     sentation of the error code.

     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.

CHARACTER ENCODING
     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.

     *	 isds_version returns locale encoded string.

     *	 Log call-back function set by isds_set_log_callback function is  called
	 with raw byte stream.

     *	 isds_pki_credentials structure string members have encoding specific to
	 cryptographic library linked to cURL library.

GLOBAL SETTINGS
     Some functions influence library behaviour globally. These are:

     *	 isds_init  and isds_cleanup used to initialize and deinitialize the li-
	 brary.

     *	 isds_set_logging and isds_set_log_callback to set logging.

LOGGING AND DEBUGGING
     Logging is global for all libdatovka calls. Log level and facility  can  be
     set with isds_set_logging function.

     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.

NETWORK INPUT/OUTPUT
     Some functions operating on a context create network sockets and do network
     input and output.

     Network  timeout  can be set with isds_set_timeout function. Function calls
     aborted owing to the timeout will return IE_TIMED_OUT.

     Network operation progress can be monitored by a  call-back  function.  The
     call-back function can be registered using isds_set_xferinfo_callback func-
     tion.  Registered call-back function will be called periodically with argu-
     ments declaring amount of transferred data. The call-back return value  de-
     termines  whether to continue in the network operation or to cancel the op-
     eration. 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.

MEMORY MANAGEMENT
     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 effec-
     tively) and returns nothing.

     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.

     Output strings are allocated using standard malloc call. Application is re-
     sponsible	for  their deallocation (in case of no failure and if not speci-
     fied otherwise.) Use standard free call for  strings,  use  libdatovka  de-
     structors for libdatovka structures.

AVAILABLE FUNCTIONS, TYPES, AND CONSTANTS
     See libdatovka/isds.h header file.

SEE ALSO
     isds.h.libdatovka(3), libcurl(3)

AUTHORS
     CZ.NIC, z. s. p. o.
	 Maintains libdatovka. Has been contributing to libisds.

     Petr P~AsaoA
	 He has written libisds.

NOTES
      1. Czech
		   ISDS Act (300/2008 Coll.)
	 http://portal.gov.cz/zakon/300/2008

      2. Dokumenty ke staA3/4enA section of
		   ISDS Information Portal
	 https://www.datoveschranky.info/ke-stazeni

[FIXME: source] 		   08/27/2026			   LIBDATOVKA(3)
home | help