'\" t
.\" Title: isds.h.libdatovka
.\" Author: CZ.NIC, z. s. p. o.
.\" Generator: DocBook XSL Stylesheets v1.79.2
.\" Date: 05/11/2024
.\" Manual: Manual for Libdatovka
.\" Source: [FIXME: source]
.\" Language: English
.\"
.TH "ISDS\&.H\&.LIBDATOVK" "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"
isds.h.libdatovka \- API definition for libdatovka
.SH "SYNOPSIS"
.sp
.nf
#include
.fi
.sp
.SH "DESCRIPTION"
.PP
This header file declares interface for the libdatovka library\&.
.SH "CONSTANTS"
.SS "Service locators"
.PP
Addresses of known
ISDS
servers\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBBase URLs of production ISDS instance\fR
.RS 4
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBisds_locator\fR
.RS (\n(SNu)
.sp
.if n \{\
.RS 4
.\}
.nf
extern const char \%\fIisds_locator\fR[];
.fi
.if n \{\
.RE
.\}
.sp
.PP
Without client certificate authentication\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBisds_cert_locator\fR
.RS (\n(SNu)
.sp
.if n \{\
.RS 4
.\}
.nf
extern const char \%\fIisds_cert_locator\fR[];
.fi
.if n \{\
.RE
.\}
.sp
.PP
With client certificate authentication\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBisds_vodz_locator\fR
.RS (\n(SNu)
.sp
.if n \{\
.RS 4
.\}
.nf
extern const char \%\fIisds_vodz_locator\fR[];
.fi
.if n \{\
.RE
.\}
.sp
.PP
High\-volume data message locator without client certificate authentication\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBisds_vodz_cert_locator\fR
.RS (\n(SNu)
.sp
.if n \{\
.RS 4
.\}
.nf
extern const char \%\fIisds_vodz_cert_locator\fR[];
.fi
.if n \{\
.RE
.\}
.sp
.PP
High\-volume data message locator with client certificate authentication\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBisds_otp_locator\fR
.RS (\n(SNu)
.sp
.if n \{\
.RS 4
.\}
.nf
extern const char \%\fIisds_otp_locator\fR[];
.fi
.if n \{\
.RE
.\}
.sp
.PP
With
OTP
authentication\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBisds_mep_locator\fR
.RS (\n(SNu)
.sp
.if n \{\
.RS 4
.\}
.nf
extern const char \%\fIisds_mep_locator\fR[];
.fi
.if n \{\
.RE
.\}
.sp
.PP
With
MEP
authentication\&.
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBBase URLs of testing ISDS instance\fR
.RS 4
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBisds_testing_locator\fR
.RS (\n(SNu)
.sp
.if n \{\
.RS 4
.\}
.nf
extern const char \%\fIisds_testing_locator\fR[];
.fi
.if n \{\
.RE
.\}
.sp
.PP
Without client certificate authentication\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBisds_cert_testing_locator\fR
.RS (\n(SNu)
.sp
.if n \{\
.RS 4
.\}
.nf
extern const char \%\fIisds_cert_testing_locator\fR[];
.fi
.if n \{\
.RE
.\}
.sp
.PP
With client certificate authentication\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBisds_vodz_testing_locator\fR
.RS (\n(SNu)
.sp
.if n \{\
.RS 4
.\}
.nf
extern const char \%\fIisds_vodz_testing_locator\fR[];
.fi
.if n \{\
.RE
.\}
.sp
.PP
High\-volume data message locator without client certificate authentication\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBisds_vodz_cert_testing_locator\fR
.RS (\n(SNu)
.sp
.if n \{\
.RS 4
.\}
.nf
extern const char \%\fIisds_vodz_cert_testing_locator\fR[];
.fi
.if n \{\
.RE
.\}
.sp
.PP
High\-volume data message locator with client certificate authentication\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBisds_otp_testing_locator\fR
.RS (\n(SNu)
.sp
.if n \{\
.RS 4
.\}
.nf
extern const char \%\fIisds_otp_testing_locator\fR[];
.fi
.if n \{\
.RE
.\}
.sp
.PP
With
OTP
authentication\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBisds_mep_testing_locator\fR
.RS (\n(SNu)
.sp
.if n \{\
.RS 4
.\}
.nf
extern const char \%\fIisds_mep_testing_locator\fR[];
.fi
.if n \{\
.RE
.\}
.sp
.PP
With
MEP
authentication\&.
.RE
.RE
.SH "DATA TYPES"
.SS "struct isds_ctx"
.sp
.if n \{\
.RS 4
.\}
.nf
struct isds_ctx;
.fi
.if n \{\
.RE
.\}
.sp
.PP
Context for specific
ISDS
box\&.
.SS "\%isds_error"
.sp
.if n \{\
.RS 4
.\}
.nf
typedef enum \%\fBisds_error\fR;
.fi
.if n \{\
.RE
.\}
.sp
.PP
Error code\&. Known values:
.PP
IE_SUCCESS
.RS 4
No error\&. Numeric value 0\&.
.RE
.PP
IE_ERROR
.RS 4
Unspecified error\&.
.RE
.PP
IE_NOTSUP
.RS 4
Operation is not supported\&.
.RE
.PP
IE_INVAL
.RS 4
Invalid value\&.
.RE
.PP
IE_INVALID_CONTEXT
.RS 4
The context is not valid\&.
.RE
.PP
IE_NOT_LOGGED_IN
.RS 4
The context has not been logged in\&.
.RE
.PP
IE_CONNECTION_CLOSED
.RS 4
Network connection has been closed\&.
.RE
.PP
IE_TIMED_OUT
.RS 4
Time limit for network operation exceeded\&.
.RE
.PP
IE_NONEXIST
.RS 4
Requested entity doesn\*(Aqt exist\&.
.RE
.PP
IE_NOMEM
.RS 4
Not enough memory\&.
.RE
.PP
IE_NETWORK
.RS 4
Network error\&.
.RE
.PP
IE_HTTP
.RS 4
Error on
HTTP
level\&.
.RE
.PP
IE_SOAP
.RS 4
Error on
SOAP
level\&.
.RE
.PP
IE_XML
.RS 4
Error on XML level\&.
.RE
.PP
IE_ISDS
.RS 4
Problem with
ISDS
server\&.
.RE
.PP
IE_ENUM
.RS 4
Invalid enumeration value\&.
.RE
.PP
IE_DATE
.RS 4
Invalid date value\&.
.RE
.PP
IE_TOO_BIG
.RS 4
Value is too big\&.
.RE
.PP
IE_TOO_SMALL
.RS 4
Value is too small\&.
.RE
.PP
IE_NOTUNIQ
.RS 4
Value is not unique\&.
.RE
.PP
IE_NOTEQUAL
.RS 4
Compared values are not equal\&.
.RE
.PP
IE_PARTIAL_SUCCESS
.RS 4
Operation on a vector succeeded for some values but failed for others\&.
.RE
.PP
IE_ABORTED
.RS 4
Operation was aborted by application request\&.
.RE
.PP
IE_SECURITY
.RS 4
Security requirements were not satisfied\&.
.RE
.SS "\%isds_log_level"
.sp
.if n \{\
.RS 4
.\}
.nf
typedef enum \%\fBisds_log_level\fR;
.fi
.if n \{\
.RE
.\}
.sp
.PP
Log level\&. Know values:
.PP
\%\fBILL_NONE\fR
.RS 4
0
.RE
.PP
\%\fBILL_CRIT\fR
.RS 4
10
.RE
.PP
\%\fBILL_ERR\fR
.RS 4
20
.RE
.PP
\%\fBILL_WARNING\fR
.RS 4
30
.RE
.PP
\%\fBILL_INFO\fR
.RS 4
40
.RE
.PP
\%\fBILL_DEBUG\fR
.RS 4
50
.RE
.PP
\%\fBILL_ALL\fR
.RS 4
100
.RE
.SS "\%isds_log_facility"
.sp
.if n \{\
.RS 4
.\}
.nf
typedef enum \%\fBisds_log_facility\fR;
.fi
.if n \{\
.RE
.\}
.sp
.PP
Log facility\&. Know values:
.PP
\%\fBILF_NONE\fR
.RS 4
0x0
.RE
.PP
\%\fBILF_HTTP\fR
.RS 4
0x1
.RE
.PP
\%\fBILF_SOAP\fR
.RS 4
0x2
.RE
.PP
\%\fBILF_ISDS\fR
.RS 4
0x4
.RE
.PP
\%\fBILF_FILE\fR
.RS 4
0x8
.RE
.PP
\%\fBILF_SEC\fR
.RS 4
0x10
.RE
.PP
\%\fBILF_XML\fR
.RS 4
0x20
.RE
.PP
\%\fBILF_ALL\fR
.RS 4
0xFF
.RE
.SS "\%isds_option"
.sp
.if n \{\
.RS 4
.\}
.nf
typedef enum \%\fBisds_option\fR;
.fi
.if n \{\
.RE
.\}
.sp
.PP
libdatovka option identifiers\&. Known values:
.PP
\%\fBIOPT_TLS_VERIFY_SERVER\fR
.RS 4
Option type is
\%\fB_Bool\fR\&. Whether to verify server identity\&. Default value is true\&.
.RE
.PP
\%\fBIOPT_TLS_CA_FILE\fR
.RS 4
Option type is
\%\fBchar *\fR\&. Option value is a file name with certificate authority certificates\&. Default value depends on used cryptographic library\&.
.RE
.PP
\%\fBIOPT_TLS_CA_DIRECTORY\fR
.RS 4
Option type is
\%\fBchar *\fR, Option value is a directory with certificate authority certificates\&. Default value depends on used cryptographic library\&.
.RE
.PP
\%\fBIOPT_TLS_CRL_FILE\fR
.RS 4
Option type is
\%\fBchar *\fR\&. Option value is a file name with certificat revocation list in
PEM
format\&. Default value depends on used cryptographic library\&.
.RE
.PP
\%\fBIOPT_NORMALIZE_MIME_TYPE\fR
.RS 4
Optiona type is
\%\fB_Bool\fR\&. Whether to normalize
MIME
type values\&. Default value is false\&.
.RE
.SS "\%isds_tls_option"
.sp
.if n \{\
.RS 4
.\}
.nf
typedef enum \%\fBisds_tls_option\fR;
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBWarning\fR
.ps -1
.br
.PP
This type is deprecated\&.
.sp .5v
.RE
.PP
TLS
libdatovka option identifiers\&. Known values:
.PP
\%\fBITLS_VERIFY_SERVER\fR
.RS 4
Option type is
\%\fB_Bool\fR\&. Whether to verify server identity\&.
.RE
.PP
\%\fBITLS_CA_FILE\fR
.RS 4
Option type is
\%\fBchar *\fR\&. Option value is a file name with certificate authority certificates\&.
.RE
.PP
\%\fBITLS_CA_DIRECTORY\fR
.RS 4
Option type is
\%\fBchar *\fR\&. Option value is a directory name with certificate authority certificates\&.
.RE
.PP
\%\fBITLS_CRL_FILE\fR
.RS 4
Option type is
\%\fBchar *\fR\&. Option value is a file name with certificate revocation list in
PEM
format\&.
.RE
.SS "\%isds_pki_format"
.sp
.if n \{\
.RS 4
.\}
.nf
typedef enum \%\fBisds_pki_format\fR;
.fi
.if n \{\
.RE
.\}
.sp
.PP
Cryptographic material encoding\&. Known values:
.PP
\%\fBPKI_FORMAT_PEM\fR
.RS 4
PEM
format\&.
.RE
.PP
\%\fBPKI_FORMAT_DER\fR
.RS 4
DER format\&.
.RE
.PP
\%\fBPKI_FORMAT_ENG\fR
.RS 4
The material is stored in a cryptographic engine\&.
.RE
.SS "struct isds_pki_credentials"
.sp
.if n \{\
.RS 4
.\}
.nf
struct isds_pki_credentials;
.fi
.if n \{\
.RE
.\}
.sp
.PP
This structure holds public key infrastructure cryptographic material to authenticate a client\&. Members are:
.PP
\%\fBchar *\fR\%\fIengine\fR;
.RS 4
String identifier of cryptographic engine to use (where key is stored)\&. Use NULL for no engine\&.
.RE
.PP
\%\fBisds_pki_format\fR \%\fIcertificate_format\fR;
.RS 4
Certificate format\&.
.RE
.PP
\%\fBchar *\fR\%\fIcertificate\fR;
.RS 4
A path to client certificate, or a certificate nickname in case of
NSS
as curl back\-end, or key slot identifier inside cryptographic engine\&. Some cryptographic engines can pair certificate with key automatically (NULL value)\&.
.RE
.PP
\%\fBisds_pki_format\fR \%\fIkey_format\fR;
.RS 4
Private key format\&.
.RE
.PP
\%\fBchar *\fR\%\fIkey\fR;
.RS 4
A path to client private key, or key identifier in case an engine is used\&.
.RE
.PP
\%\fBchar *\fR\%\fIpassphrase\fR;
.RS 4
Zero terminated string with password for decrypting private key, or engine
PIN\&. Use NULL for no pass\-phrase or to let the engine to ask for it\&.
.RE
.SS "\%isds_otp_method"
.sp
.if n \{\
.RS 4
.\}
.nf
typedef enum \%\fBisds_otp_method\fR;
.fi
.if n \{\
.RE
.\}
.sp
.PP
One\-time password authentication method\&. Known values:
.PP
\%\fBOTP_HMAC\fR
.RS 4
HMAC\-based
OTP
method\&.
.RE
.PP
\%\fBOTP_TIME\fR
.RS 4
Time\-based
OTP
method\&.
.RE
.SS "\%isds_otp_resolution"
.sp
.if n \{\
.RS 4
.\}
.nf
typedef enum \%\fBisds_otp_resolution\fR;
.fi
.if n \{\
.RE
.\}
.sp
.PP
One\-time password authentication resolution\&. Known values:
.PP
\%\fBOTP_RESOLUTION_SUCCESS\fR
.RS 4
Authentication succeeded\&.
.RE
.PP
\%\fBOTP_RESOLUTION_UNKNOWN\fR
.RS 4
Status is unknown\&.
.RE
.PP
\%\fBOTP_RESOLUTION_BAD_AUTHENTICATION\fR
.RS 4
Bad log\-in\&. You can retry to log in\&.
.RE
.PP
\%\fBOTP_RESOLUTION_ACCESS_BLOCKED\fR
.RS 4
Access blocked for 60 minutes\&. (Because a brute force attack was detected\&.)
.RE
.PP
\%\fBOTP_RESOLUTION_PASSWORD_EXPIRED\fR
.RS 4
Password has expired\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
It\*(Aqs not clear which password expired:
OTP
or regular password?
.sp .5v
.RE
.RE
.PP
\%\fBOTP_RESOLUTION_TOO_FAST\fR
.RS 4
OTP
cannot be sent repeatedly at this rate\&. (Minimal delay depends on
TOTP
window setting\&.)
.RE
.PP
\%\fBOTP_RESOLUTION_UNAUTHORIZED\fR
.RS 4
User name is not allowed to access requested
URI\&.
.RE
.PP
\%\fBOTP_RESOLUTION_TOTP_SENT\fR
.RS 4
OTP
has been generated and sent by the
ISDS
to the user\&.
.RE
.PP
\%\fBOTP_RESOLUTION_TOTP_NOT_SENT\fR
.RS 4
OTP
could not been sent by the
ISDS\&. Retry later\&.
.RE
.SS "struct isds_otp"
.sp
.if n \{\
.RS 4
.\}
.nf
struct isds_otp;
.fi
.if n \{\
.RE
.\}
.sp
.PP
This structure holds one\-time password when authenticating a client and resolution of the authentication\&.
.PP
Input members are:
.PP
\%\fBisds_otp_method\fR \%\fImethod\fR;
.RS 4
Select
OTP
method to use\&.
.RE
.PP
\%\fBchar *\fR\%\fIotp_code\fR;
.RS 4
One\-time password to use\&. Pass NULL, if you do not know it yet (e\&.g\&.
in case of first phase of time\-based
OTP
authentication to request new code from
ISDS\&.)
.RE
.PP
Output members are:
.PP
\%\fBisds_otp_resolution\fR \%\fIresolution\fR;
.RS 4
Fine\-grade resolution of this
OTP
authentication attempt\&.
.RE
.SS "\%isds_DbType"
.sp
.if n \{\
.RS 4
.\}
.nf
typedef enum \%\fBisds_DbType\fR;
.fi
.if n \{\
.RE
.\}
.sp
.PP
Box type\&. It classifies box owner by his legal status\&. Known values:
.PP
\%\fBDBTYPE_OVM_MAIN\fR
.RS 4
This is a special value for
\%\fBisds_find_box_by_fulltext\fR\&. It\*(Aqs not accepted by any other
services\&.
.RE
.PP
\%\fBDBTYPE_SYSTEM\fR
.RS 4
This is a special value for sender of messages sent by the
ISDS\&. You can find it only in incoming messages\&. It\*(Aqs not accepted by any other
services\&.
.RE
.PP
\%\fBDBTYPE_OVM\fR
.RS 4
Standard government (state or municipality or similar) office\&.
.RE
.PP
\%\fBDBTYPE_OVM_NOTAR\fR
.RS 4
Notary (stopped being used, replaced with
OVM_PFO)\&.
.RE
.PP
\%\fBDBTYPE_OVM_EXEKUT\fR
.RS 4
Executor (stopped being used, replaced with
OVM_PFO)\&.
.RE
.PP
\%\fBDBTYPE_OVM_REQ\fR
.RS 4
Subsidiary office with
OVM
(governing) status assigned on request (section 6 and 7 of the act)\&.
.RE
.PP
\%\fBDBTYPE_OVM_FO\fR
.RS 4
Natural person with
OVM
status (without identification number)\&.
.RE
.PP
\%\fBDBTYPE_OVM_PFO\fR
.RS 4
Natural person in business with
OVM
status (e\&.g\&. notary or executor)\&.
.RE
.PP
\%\fBDBTYPE_OVM_PO\fR
.RS 4
Juridical person with
OVM
status (arisen from previously existing
PO
or
PO_REQ)\&.
.RE
.PP
\%\fBDBTYPE_PO\fR
.RS 4
Standard commercial organization (listed in trade registry)\&.
.RE
.PP
\%\fBDBTYPE_PO_ZAK\fR
.RS 4
Other organization founded by an act (stopped being used, replaced with
PO)\&.
.RE
.PP
\%\fBDBTYPE_PO_REQ\fR
.RS 4
An organization with a box assigned on its request\&.
.RE
.PP
\%\fBDBTYPE_PFO\fR
.RS 4
Person in business\&.
.RE
.PP
\%\fBDBTYPE_PFO_ADVOK\fR
.RS 4
Lawyer\&.
.RE
.PP
\%\fBDBTYPE_PFO_DANPOR\fR
.RS 4
Tax consultant\&.
.RE
.PP
\%\fBDBTYPE_PFO_INSSPR\fR
.RS 4
Administrator of insolvency (stopped being used, replaced with
OVM_PFO)\&.
.RE
.PP
\%\fBDBTYPE_PFO_AUDITOR\fR
.RS 4
Statutory auditor\&.
.RE
.PP
\%\fBDBTYPE_PFO_ZNALEC\fR
.RS 4
Expert witness\&.
.RE
.PP
\%\fBDBTYPE_PFO_TLUMOCNIK\fR
.RS 4
Sworn translator\&.
.RE
.PP
\%\fBDBTYPE_PFO_ARCH\fR
.RS 4
Architect\&.
.RE
.PP
\%\fBDBTYPE_PFO_AIAT\fR
.RS 4
Authorised engineer / technician\&.
.RE
.PP
\%\fBDBTYPE_PFO_AZI\fR
.RS 4
Authorised geodetics engineer\&.
.RE
.PP
\%\fBDBTYPE_PFO_REQ\fR
.RS 4
Person in business on its request\&.
.RE
.PP
\%\fBDBTYPE_FO\fR
.RS 4
Standard person\&.
.RE
.PP
Some interfaces refer to
\fIgross\fR
box type\&. These are the shortest names of the identifiers\&. For example,
DBTYPE_OVM
is a gross type for
DB_OVM_NOTAR
or
DBTYPE_OVM\&. But not for
DBTYPE_PO\&.
.SS "\%isds_DbState"
.sp
.if n \{\
.RS 4
.\}
.nf
typedef enum \%\fBisds_DbState\fR;
.fi
.if n \{\
.RE
.\}
.sp
.PP
Box status from point of view of accessibility\&. Known values:
.PP
\%\fBDBSTATE_ACCESSIBLE\fR
.RS 4
The box is accessible\&.
.RE
.PP
\%\fBDBSTATE_TEMP_INACCESSIBLE\fR
.RS 4
The box is temporarily inaccessible (at the request of the user)\&.
.RE
.PP
\%\fBDBSTATE_NOT_YET_ACCESSIBLE\fR
.RS 4
The box has not yet been activated\&.
.RE
.PP
\%\fBDBSTATE_PERM_INACCESSIBLE\fR
.RS 4
The box is permanently inaccessible\&.
.RE
.PP
\%\fBDBSTATE_REMOVED\fR
.RS 4
The box has been removed\&.
.RE
.PP
\%\fBDBSTATE_TEMP_INACCESSIBLE_LAW\fR
.RS 4
The box is temporarily inaccessible (because of the reasons enumerated in the law)\&.
.RE
.SS "\%isds_privileges"
.sp
.if n \{\
.RS 4
.\}
.nf
typedef enum \%\fBisds_privileges\fR;
.fi
.if n \{\
.RE
.\}
.sp
.PP
Distinct user permissions from point of view of
ISDS\&. Instances can be bitmaps of any of these distinct values\&. Distinct known values are:
.PP
\%\fBPRIVIL_READ_NON_PERSONAL\fR
.RS 4
The user can download and read messages with
\%\fIdmPersonalDelivery\fR
equal to false\&.
.RE
.PP
\%\fBPRIVIL_READ_ALL\fR
.RS 4
The user can download and read messages with
\%\fIdmPersonalDelivery\fR
equal to true\&.
.RE
.PP
\%\fBPRIVIL_CREATE_DM\fR
.RS 4
The user can create and send messages, the user can download outgoing (sent) messages\&.
.RE
.PP
\%\fBPRIVIL_VIEW_INFO\fR
.RS 4
The user can list messages and read data about a message post and delivery\&.
.RE
.PP
\%\fBPRIVIL_SEARCH_DB\fR
.RS 4
The user can can search for boxes\&.
.RE
.PP
\%\fBPRIVIL_OWNER_ADM\fR
.RS 4
The user can administer his box (to add and remove permitted users and to modify theirs permissions\&.)
.RE
.PP
\%\fBPRIVIL_READ_VAULT\fR
.RS 4
The user can read messages stored in the long term storage\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
This permission is not used since 2012\-05\&.
.sp .5v
.RE
.RE
.PP
\%\fBPRIVIL_ERASE_VAULT\fR
.RS 4
The user can delete messages from the long term storage\&.
.RE
.SS "\%enum isds_message_status"
.sp
.if n \{\
.RS 4
.\}
.nf
typedef enum isds_message_status \%\fBisds_message_status\fR;
.fi
.if n \{\
.RE
.\}
.sp
.PP
Message status\&. Known values are:
.PP
\%\fBMESSAGESTATE_SENT\fR
.RS 4
The message has been put into
ISDS\&.
.RE
.PP
\%\fBMESSAGESTATE_STAMPED\fR
.RS 4
Message was stamped by a time stamp authority\&.
.RE
.PP
\%\fBMESSAGESTATE_INFECTED\fR
.RS 4
The message included viruses\&. Infected documents have been removed from the message\&.
.RE
.PP
\%\fBMESSAGESTATE_DELIVERED\fR
.RS 4
The message was delivered\&. (\%\fIdmDeliveryTime\fR
is populated\&.)
.RE
.PP
\%\fBMESSAGESTATE_SUBSTITUTED\fR
.RS 4
The message was delivered through fiction,
\%\fIdmAcceptanceTime\fR
is populated\&.
.RE
.PP
\%\fBMESSAGESTATE_RECEIVED\fR
.RS 4
The message was accepted (by user\*(Aqs log\-in or user\*(Aqs explicit request)\&.
\%\fIdmAcceptanceTime\fR
is populated\&.
.RE
.PP
\%\fBMESSAGESTATE_READ\fR
.RS 4
The message has been read by a user\&.
.RE
.PP
\%\fBMESSAGESTATE_UNDELIVERABLE\fR
.RS 4
The message could not been delivered\&. (E\&.g\&.The recipient\*(Aqs box has been made inaccessible meantime\&.)
.RE
.PP
\%\fBMESSAGESTATE_REMOVED\fR
.RS 4
The message\*(Aqs content was deleted\&.
.RE
.PP
\%\fBMESSAGESTATE_IN_VAULT\fR
.RS 4
The message is stored in the long term storage\&.
.RE
.PP
The values can be combined into a bit mask for some functions\&. A special
\%\fBMESSAGESTATE_ANY\fR
macro denotes any of the states\&.
.SS "\%isds_hash_algorithm"
.sp
.if n \{\
.RS 4
.\}
.nf
typedef enum \%\fBisds_hash_algorithm\fR;
.fi
.if n \{\
.RE
.\}
.sp
.PP
Hash algorithm types\&. Known values are:
.PP
\%\fBHASH_ALGORITHM_MD5\fR
.RS 4
MD5\&.
.RE
.PP
\%\fBHASH_ALGORITHM_SHA_1\fR
.RS 4
SHA\-1\&.
.RE
.PP
\%\fBHASH_ALGORITHM_SHA_224\fR
.RS 4
SHA\-224\&.
.RE
.PP
\%\fBHASH_ALGORITHM_SHA_256\fR
.RS 4
SHA\-256\&.
.RE
.PP
\%\fBHASH_ALGORITHM_SHA_384\fR
.RS 4
SHA\-384\&.
.RE
.PP
\%\fBHASH_ALGORITHM_SHA_512\fR
.RS 4
SHA\-256\&.
.RE
.SS "\%isds_buffer_strategy"
.sp
.if n \{\
.RS 4
.\}
.nf
typedef enum \%\fBisds_buffer_strategy\fR;
.fi
.if n \{\
.RE
.\}
.sp
.PP
Buffer storage strategy\&. This type defines how a function should embed application provided buffer into
\%\fIraw\fR
element of output structure\&. Known values are:
.PP
\%\fBBUFFER_DONT_STORE\fR
.RS 4
Don\*(Aqt fill
\%\fIraw\fR
member\&.
.RE
.PP
\%\fBBUFFER_COPY\fR
.RS 4
Copy buffer content into newly allocated
\%\fIraw\fR
member\&.
.RE
.PP
\%\fBBUFFER_MOVE\fR
.RS 4
Copy pointer\&. Leave deallocation to structure destructor (\%\fBisds_*_free\fR())\&.
.RE
.SS "struct isds_hash"
.sp
.if n \{\
.RS 4
.\}
.nf
struct isds_hash;
.fi
.if n \{\
.RE
.\}
.sp
.PP
This is a hash value storage\&. Members are:
.PP
\%\fBisds_hash_algorithm\fR \%\fIalgorithm\fR;
.RS 4
Hash algorithm\&.
.RE
.PP
\%\fBsize_t\fR \%\fIlength\fR;
.RS 4
Hash value length in bytes\&.
.RE
.PP
\%\fBvoid *\fR\%\fIvalue\fR;
.RS 4
Hash value as a byte stream\&.
.RE
.SS "struct isds_PersonName"
.sp
.if n \{\
.RS 4
.\}
.nf
struct isds_PersonName;
.fi
.if n \{\
.RE
.\}
.sp
.PP
Name of a person\&. Members are:
.PP
\%\fBchar *\fR\%\fIpnFirstName\fR;
.RS 4
First name\&.
.RE
.PP
\%\fBchar *\fR\%\fIpnMiddleName\fR;
.RS 4
Middle name\&.
.RE
.PP
\%\fBchar *\fR\%\fIpnLastName\fR;
.RS 4
Current last name\&.
.RE
.PP
\%\fBchar *\fR\%\fIpnLastNameAtBirth\fR;
.RS 4
Last name at birth\&.
.RE
.SS "struct isds_BirthInfo"
.sp
.if n \{\
.RS 4
.\}
.nf
struct isds_BirthInfo;
.fi
.if n \{\
.RE
.\}
.sp
.PP
Date and place of a birth\&. Members are:
.PP
\%\fBstruct tm *\fR\%\fIbiDate\fR;
.RS 4
Date of birth in local time at the birth place\&. Only
\%\fItm_year\fR,
\%\fItm_mon\fR
and
\%\fItm_mday\fR
members of the
\%\fBstruct tm\fR
carry sane value\&. Others are undefined\&.
.RE
.PP
\%\fBchar *\fR\%\fIbiCity\fR;
.RS 4
City where a person was born\&.
.RE
.PP
\%\fBchar *\fR\%\fIbiCounty\fR;
.RS 4
Region where a person was born\&. This is the kind of region that is called
Bezirk
in German and
okres
in Czech\&.
.RE
.PP
\%\fBchar *\fR\%\fIbiState\fR;
.RS 4
State wher a person was born\&.
.RE
.SS "struct isds_Address"
.sp
.if n \{\
.RS 4
.\}
.nf
struct isds_Address;
.fi
.if n \{\
.RE
.\}
.sp
.PP
Postal address\&. Members are:
.PP
\%\fBchar *\fR\%\fIadCity\fR;
.RS 4
City\&.
.RE
.PP
\%\fBchar *\fR\%\fIadStreet\fR;
.RS 4
Street\&.
.RE
.PP
\%\fBchar *\fR\%\fIadNumberInStreet\fR;
.RS 4
Identification of an entrance on the street\&.
Číslo orientační
in Czech\&.
.RE
.PP
\%\fBchar *\fR\%\fIadNumberInMunicipality\fR;
.RS 4
Identification of a building in the municipality\&.
Číslo popisné
in Czech\&.
.RE
.PP
\%\fBchar *\fR\%\fIadZipCode\fR;
.RS 4
Postal code for mail routing\&.
.RE
.PP
\%\fBchar *\fR\%\fIadState\fR;
.RS 4
State\&.
.RE
.SS "struct isds_DbOwnerInfo"
.sp
.if n \{\
.RS 4
.\}
.nf
struct isds_DbOwnerInfo;
.fi
.if n \{\
.RE
.\}
.sp
.PP
Data about a box and his owner\&. NULL pointer values mean undefined values\&. Members are:
.PP
\%\fBchar *\fR\%\fIdbID\fR;
.RS 4
Box identifier\&. Specification limits the length to 7 characters\&.
.RE
.PP
\%\fBisds_DbType *\fR\%\fIdbType\fR;
.RS 4
Box type\&.
.RE
.PP
\%\fBchar *\fR\%\fIic\fR;
.RS 4
Identifier of the owner\&.
.RE
.PP
\%\fBisds_PersonName *\fR\%\fIpersonName\fR;
.RS 4
Name of a person owning the box\&.
.RE
.PP
\%\fBchar *\fR\%\fIfirmName\fR;
.RS 4
Name of a firm owning the box\&.
.RE
.PP
\%\fBisds_BirthInfo *\fR\%\fIbirthInfo\fR;
.RS 4
Birth details of the person\&.
.RE
.PP
\%\fBisds_Address *\fR\%\fIaddress\fR;
.RS 4
Postal address of the owner\&.
.RE
.PP
\%\fBchar *\fR\%\fInationality\fR;
.RS 4
Nationality of the owner\&.
.RE
.PP
\%\fBchar *\fR\%\fIemail\fR;
.RS 4
E\-mail addres of the owner\&.
.RE
.PP
\%\fBchar *\fR\%\fItelNumber\fR;
.RS 4
Telephone number of the owner\&.
.RE
.PP
\%\fBchar *\fR\%\fIidentifier\fR;
.RS 4
External box identifier for data provider (OVM,
PO, maybe
PFO
box types\&.) Specification limits the length to 20 characters\&.
.RE
.PP
\%\fBchar *\fR\%\fIregistryCode\fR;
.RS 4
PFO
external registry code\&. Specification limits the length to 5 characters\&.
.RE
.PP
\%\fBlong int *\fR\%\fIdbState\fR;
.RS 4
Box state\&. 1 means the box is active\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
The type is long int because specification declares it as
\%\fBxsd:integer\fR\&.
.sp .5v
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
TODO: enum?
.sp .5v
.RE
.RE
.PP
\%\fB_Bool *\fR\%\fIdbEffectiveOVM\fR;
.RS 4
The Box has
OVM
role (section\ 5a of the act)\&.
.RE
.PP
\%\fB_Bool *\fR\%\fIdbOpenAddressing\fR;
.RS 4
This non\-OVM
box is free to receive messages from anybody\&.
.RE
.SS "\%isds_UserType"
.sp
.if n \{\
.RS 4
.\}
.nf
typedef enum \%\fBisds_UserType\fR;
.fi
.if n \{\
.RE
.\}
.sp
.PP
User type\&. Known values are:
.PP
\%\fBUSERTYPE_PRIMARY\fR
.RS 4
Owner of the box\&.
.RE
.PP
\%\fBUSERTYPE_ENTRUSTED\fR
.RS 4
User with limited access to the box\&.
.RE
.PP
\%\fBUSERTYPE_ADMINISTRATOR\fR
.RS 4
User who can manage
\%\fBUSERTYPE_ENTRUSTED\fR
users\&.
.RE
.PP
\%\fBUSERTYPE_OFFICIAL\fR
.RS 4
???
.RE
.PP
\%\fBUSERTYPE_OFFICIAL_CERT\fR
.RS 4
???
.RE
.PP
\%\fBUSERTYPE_LIQUIDATOR\fR
.RS 4
Company liquidator\&.
.RE
.PP
\%\fBUSERTYPE_RECEIVER\fR
.RS 4
Company receiver\&.
.RE
.PP
\%\fBUSERTYPE_GUARDIAN\fR
.RS 4
Legal guardian\&.
.RE
.SS "struct isds_DbUserInfo"
.sp
.if n \{\
.RS 4
.\}
.nf
struct isds_DbUserInfo;
.fi
.if n \{\
.RE
.\}
.sp
.PP
Data about a user\&. NULL pointer values mean undefined values\&. Members are:
.PP
\%\fBchar *\fR\%\fIuserID\fR;
.RS 4
User identifier\&. Specification limits the length from 6 to 12 characters\&.
.RE
.PP
\%\fBisds_UserType *\fR\%\fIuserType\fR;
.RS 4
User type\&.
.RE
.PP
\%\fBlong int *\fR\%\fIuserPrivils\fR;
.RS 4
Set of user permissions\&.
.RE
.PP
\%\fBisds_PersonName *\fR\%\fIpersonName\fR;
.RS 4
Name of the user\&.
.RE
.PP
\%\fBisds_Address *\fR\%\fIaddress\fR;
.RS 4
Postal address of the user\&.
.RE
.PP
\%\fBstruct tm *\fR\%\fIbiDate\fR;
.RS 4
Date of birth in local time\&. Only
\%\fItm_year\fR,
\%\fItm_mon\fR
and
\%\fItm_mday\fR
members of the
\%\fBstruct tm\fR
carry sane value\&. Others are undefined\&.
.RE
.PP
\%\fBchar *\fR\%\fIic\fR;
.RS 4
Identifier a supervising firm\&. Specification limits the length to 8 characters\&.
.RE
.PP
\%\fBchar *\fR\%\fIfirmName\fR;
.RS 4
Name of a supervising firm\&. Specification limits the length to 100 characters\&.
.RE
.PP
\%\fBchar *\fR\%\fIcaStreet\fR;
.RS 4
Contact address\&. Street and number\&.
.RE
.PP
\%\fBchar *\fR\%\fIcaCity\fR;
.RS 4
Czech city of the contact address\&.
.RE
.PP
\%\fBchar *\fR\%\fIcaZipCode\fR;
.RS 4
Postal code of the contact address\&.
.RE
.PP
\%\fBchar *\fR\%\fIcaState\fR;
.RS 4
Abbreviated country of contact address\&. This value is optional and implicit meaning is
\%\fBCZ\fR\&.
.RE
.SS "\%isds_event_type"
.sp
.if n \{\
.RS 4
.\}
.nf
typedef enum \%\fBisds_event_type\fR;
.fi
.if n \{\
.RE
.\}
.sp
.PP
Message event type\&. Known values are:
.PP
\%\fBEVENT_UNKNOWN\fR
.RS 4
Event unknown to this library\&.
.RE
.PP
\%\fBEVENT_ACCEPTED_BY_RECIPIENT\fR
.RS 4
Message has been delivered and accepted by recipient action\&.
.RE
.PP
\%\fBEVENT_ACCEPTED_BY_FICTION\fR
.RS 4
Message has been delivered, acceptance period timed out, the message is considered accepted\&.
.RE
.PP
\%\fBEVENT_ACCEPTED_BY_FICTION_NO_USER\fR
.RS 4
Message has been delivered, acceptance period timed out because there was no user who could accept the message\&.
.RE
.PP
\%\fBEVENT_UNDELIVERABLE\fR
.RS 4
Recipient box was made inaccessible, thus the message is undeliverable\&.
.RE
.PP
\%\fBEVENT_COMMERCIAL_ACCEPTED\fR
.RS 4
Recipient confirmed acceptance of this commercial message\&.
.RE
.PP
\%\fBEVENT_ENTERED_SYSTEM\fR
.RS 4
The message entered the
ISDSsystem,
i\&.e\&.
it has been just sent by a sender\&.
.RE
.PP
\%\fBEVENT_DELIVERED\fR
.RS 4
The message has been delivered into recipient\*(Aqs box\&.
.RE
.PP
\%\fBEVENT_PRIMARY_LOGIN\fR
.RS 4
Primary user logged into recipient\*(Aqs box\&.
.RE
.PP
\%\fBEVENT_ENTRUSTED_LOGIN\fR
.RS 4
Entrusted user with capability to read logged into recipient\*(Aqs box\&.
.RE
.PP
\%\fBEVENT_SYSCERT_LOGIN\fR
.RS 4
An application authenticated by
\fIsystem\fR
certificate logged into recipient\*(Aqs box\&.
.RE
.SS "struct isds_event"
.sp
.if n \{\
.RS 4
.\}
.nf
struct isds_event;
.fi
.if n \{\
.RE
.\}
.sp
.PP
An event that happened in a message life\&. All members are optional\&. Members are:
.PP
\%\fBstruct isds_timeval *\fR\%\fItime\fR;
.RS 4
When the event occurred\&.
.RE
.PP
\%\fBisds_event_type *\fR\%\fItype\fR;
.RS 4
Type of the event\&.
.RE
.PP
\%\fBchar *\fR\%\fIdescription\fR;
.RS 4
Human\-readable event description generated by the
ISDS
system\&. (Very probably in Czech language)\&.
.RE
.SS "\%enum isds_IdLevel_value"
.sp
.if n \{\
.RS 4
.\}
.nf
\%\fBenum isds_IdLevel_value\fR;
.fi
.if n \{\
.RE
.\}
.sp
.PP
Specifies which information the sender of a data message wants to publish about his person\&.
.PP
\%\fBPUBLISH_USERTYPE\fR
.RS 4
Publish information about the sender type\&. This information is always revealed to the recipient\&.
.RE
.PP
\%\fBPUBLISH_PERSONNAME\fR
.RS 4
Publish sender\*(Aqs personal name\&.
.RE
.PP
\%\fBPUBLISH_BIDATE\fR
.RS 4
Publish sender\*(Aqs birth date\&.
.RE
.PP
\%\fBPUBLISH_BICITY\fR
.RS 4
Publish sender\*(Aqs birth city\&. This information is available only when sender is SENDERTYPE_ENTRUSTED of a FO or PFO box\&.
.RE
.PP
\%\fBPUBLISH_BICOUNTY\fR
.RS 4
Publish sender\*(Aqs birth county\&. This information is available only when sender is SENDERTYPE_ENTRUSTED of a FO or PFO box\&.
.RE
.PP
\%\fBPUBLISH_ADCODE\fR
.RS 4
Publish sender\*(Aqs RUIAN address code\&.
.RE
.PP
\%\fBPUBLISH_FULLADDRESS\fR
.RS 4
Publish sender\*(Aqs full address\&.
.RE
.PP
\%\fBPUBLISH_ROBIDENT\fR
.RS 4
Publish information whether sender is identified within the ROB\&.
.RE
.SS "struct isds_envelope"
.sp
.if n \{\
.RS 4
.\}
.nf
struct isds_envelope;
.fi
.if n \{\
.RE
.\}
.sp
.PP
Message envelope\&. These are the metadata about a message\&. It does contain the message documents\&.
.PP
Be ware that the string length constraints are forced only on output members transmitted to the
ISDS\&. The other direction (downloading from the
ISDS) can break these rules\&. It should not happen, but nobody knows how much incompatible new version of the
ISDS
protocol will be\&. This is the gold Internet rule: be strict on what you send, be tolerant on what you receive\&.
.PP
Following members apply to incoming messages only:
.PP
\%\fBchar *\fR\%\fIdmID\fR;
.RS 4
Message identifier\&. Maximal length is 20 characters\&.
.RE
.PP
\%\fBchar *\fR\%\fIdbIDSender\fR;
.RS 4
Box identifier of the sender\&. Special value
aaaaaaa
means the message was sent by the
ISDS
system\&. Not by another user\&. Maximal length is 7 characters\&.
.RE
.PP
\%\fBchar *\fR\%\fIdmSender\fR;
.RS 4
Sender\*(Aqs name\&. Maximal length is 100 characters\&.
.RE
.PP
\%\fBchar *\fR\%\fIdmSenderAddress\fR;
.RS 4
Postal address of the sender\&. Maximal length is 100 characters\&.
.RE
.PP
\%\fBlong int *\fR\%\fIdmSenderType\fR;
.RS 4
Gross box type of the sender\&. You can use
\%\fBisds_DbType\fR
to enumerate some known box types\&. This is a generic integer because the protocol keeps the value unconstrained and the library must support any syntactically correct value\&.
.RE
.PP
\%\fBchar *\fR\%\fIdmRecipient\fR;
.RS 4
Recipient\*(Aqs name\&. Maximal length is 100 characters\&.
.RE
.PP
\%\fBchar *\fR\%\fIdmRecipientAddress\fR;
.RS 4
Postal address of the recipient\&. Maximal length is 100 characters\&.
.RE
.PP
\%\fB_Bool *\fR\%\fIdmAmbiguousRecipient\fR;
.RS 4
The recipient has
OVM
role\&.
.RE
.PP
Following members are assigned by the
ISDS
in different phases of message life cycle:
.PP
\%\fBunsigned long int *\fR\%\fIdmOrdinal\fR;
.RS 4
Ordinal number in list of incoming/outgoing messages\&.
.RE
.PP
\%\fBenum isds_message_status *\fR\%\fIdmMessageStatus\fR;
.RS 4
Message state\&.
.RE
.PP
\%\fBlong int *\fR\%\fIdmAttachmentSize\fR;
.RS 4
Size of message documents in kilobytes\&. The value is rounded\&.
.RE
.PP
\%\fBstruct isds_timeval *\fR\%\fIdmDeliveryTime\fR;
.RS 4
The time of delivering the message into recipient\*(Aqs box\&. It will be
\%\fBNULL\fR, if the message has not been delivered yet\&.
.RE
.PP
\%\fBstruct isds_timeval *\fR\%\fIdmAcceptanceTime\fR;
.RS 4
The time of accepting the message by the recipient\&. It will be
\%\fBNULL\fR, if message has not been accepted yet\&.
.RE
.PP
\%\fBstruct isds_hash *\fR\%\fIhash\fR;
.RS 4
The message digest\&. This is a hash of a substring representing
isds:dmDM
XML
subtree\&. You can use
\%\fBisds_compute_message_hash\fR
function to compute a hash of the message and then compare it against this structure member using
\%\fBisds_hash_cmp\fR
function\&.
.RE
.PP
\%\fBvoid *\fR\%\fItimestamp\fR;
.RS 4
This is a binary image of a qualified time stamp of the
\%\fIhash\fR
value\&. The time stamp is provided by the
ISDS
system\&. Messages that have not yet been stamped will have this value
\%\fBNULL\fR\&.
.RE
.PP
\%\fBsize_t\fR \%\fItimestamp_length\fR;
.RS 4
Length of the
\%\fItimestamp\fR
value in bytes\&.
.RE
.PP
\%\fBstruct isds_list *\fR\%\fIevents\fR;
.RS 4
Events the message passed trough\&. It\*(Aqs a list of
\%\fBisds_event\fR
structures\&.
.RE
.PP
Following members apply to both outgoing and incoming messages:
.PP
\%\fBchar *\fR\%\fIdmSenderOrgUnit\fR;
.RS 4
Sender\*(Aqs organisation unit as a string\&. This is optional\&.
.RE
.PP
\%\fBlong int *\fR\%\fIdmSenderOrgUnitNum\fR;
.RS 4
Sender\*(Aqs organisation unit as a number\&. This is optional\&.
.RE
.PP
\%\fBchar *\fR\%\fIdbIDRecipient\fR;
.RS 4
Recipient\*(Aqs box identifier\&. This is mandatory\&. Maximal length is 7 characters\&.
.RE
.PP
\%\fBchar *\fR\%\fIdmRecipientOrgUnit\fR;
.RS 4
Recipient\*(Aqs organisation unit as a string\&. This is optional\&.
.RE
.PP
\%\fBlong int *\fR\%\fIdmRecipientOrgUnitNum\fR;
.RS 4
Recipient\*(Aqs organisation unit of as a number\&. This is optional\&.
.RE
.PP
\%\fBchar *\fR\%\fIdmToHands\fR;
.RS 4
A person in recipient\*(Aqs organisation\&. This is optional\&.
.RE
.PP
\%\fBchar *\fR\%\fIdmAnnotation\fR;
.RS 4
A subject (title) of the message\&. Maximal length is 255 characters\&.
.RE
.PP
\%\fBchar *\fR\%\fIdmRecipientRefNumber\fR;
.RS 4
Czech:
číslo jednací příjemce\&. This is optional\&. Maximal length is 50 characters\&.
.RE
.PP
\%\fBchar *\fR\%\fIdmSenderRefNumber\fR;
.RS 4
Czech:
číslo jednací odesílatele\&. This is optional\&. Maximal length is 50 chars\&.
.RE
.PP
\%\fBchar *\fR\%\fIdmRecipientIdent\fR;
.RS 4
Czech:
spisová značka příjemce\&. This is optional\&. Maximal length is 50 characters\&.
.RE
.PP
\%\fBchar *\fR\%\fIdmSenderIdent\fR;
.RS 4
Czech:
spisová značka odesílatele
This is optional\&. Maximal length is 50 chars\&.
.RE
.PP
Following five members constitute a reference to an item from the Czech Act Collection\&. The human\-readable reference looks like
\fIPoint\fR (\fIParagraph\fR) \(sc \fISection\fR \fILaw\fR/\fIYear\fR Coll\&.
The members apply to both incoming and outgoing messages:
.PP
\%\fBlong int *\fR\%\fIdmLegalTitleLaw\fR;
.RS 4
A number of an act mandating the authority\&.
.RE
.PP
\%\fBlong int *\fR\%\fIdmLegalTitleYear\fR;
.RS 4
A year of issuing the act mandating the authority\&.
.RE
.PP
\%\fBchar *\fR\%\fIdmLegalTitleSect\fR;
.RS 4
A section of the act mandating the authority\&. Czech:
paragraf\&.
.RE
.PP
\%\fBchar *\fR\%\fIdmLegalTitlePar\fR;
.RS 4
A paragraph of the act mandating the authority\&. Czech:
odstavec\&.
.RE
.PP
\%\fBchar *\fR\%\fIdmLegalTitlePoint\fR;
.RS 4
A point of the act mandating the authority\&. Czech:
písmeno\&.
.RE
.PP
Other incoming/outgoing message members:
.PP
\%\fB_Bool *\fR\%\fIdmPersonalDelivery\fR;
.RS 4
If true, only person with higher privileges can read this message\&.
.RE
.PP
\%\fB_Bool *\fR\%\fIdmAllowSubstDelivery\fR;
.RS 4
Allow delivery through fiction\&.
I\&.e\&.
Even if the recipient did not read this message, the message is considered as delivered after (currently) 10 days\&. This is called
delivery through fiction\&. Only OVM dbType sender can set it\&.
.RE
.PP
\%\fBchar *\fR\%\fIdmType\fR;
.RS 4
Message type (commercial subtypes or government message)\&.
.sp
Input values (when sending the message):
.PP
"I"
.RS 4
A commercial message offering paying the response (initiatory message)\&. It\*(Aqs necessary to define
\%\fIdmSenderRefNumber\fR
member\&.
.RE
.PP
"K"
.RS 4
A commercial message paid by the sender\&.
.RE
.PP
"O"
.RS 4
A commercial response paid by the sender of a initiatory message\&. It\*(Aqs necessary to copy a value from the
\%\fIdmSenderRefNumber\fR
of the initiatory message to the
\%\fIdmRecipientRefNumber\fR
of this message\&.
.RE
.PP
"V"
.RS 4
A non\-commercial government message\&. This is the default meaning if the value is undefined while sending a message\&.
.RE
.sp
Output values (when retrieving the message):
.PP
"A"
.RS 4
This is a subsidized initiatory commercial message which can pay a response\&.
.RE
.PP
"B"
.RS 4
This is a subsidized initiatory commercial message which has already paid the response\&.
.RE
.PP
"C"
.RS 4
This is a subsidized initiatory commercial message where the response offer has expired\&.
.RE
.PP
"D"
.RS 4
This is an externally subsidized commercial message\&.
.RE
.PP
"E"
.RS 4
This is a commercial message prepaid by a stamp\&.
.RE
.PP
"G"
.RS 4
This is a commercial message paid by a sponsor\&.
.RE
.PP
"I"
.RS 4
See the input values\&.
.RE
.PP
"K"
.RS 4
See the input values\&.
.RE
.PP
"O"
.RS 4
See the input values\&.
.RE
.PP
"V"
.RS 4
See the input values\&.
.RE
.PP
"X"
.RS 4
This is an initiatory commercial message where the response offer has expired\&.
.RE
.PP
"Y"
.RS 4
This is an initiatory commercial message which has already paid the response\&.
.RE
.PP
"Z"
.RS 4
This is limitedly subsidized commercial message\&.
.RE
.sp
Length of the value is exactly 1 UTF\-8 character if defined\&. That means it\*(Aqs still zero\-terminated character string\&.
.RE
.PP
\%\fB_Bool *\fR\%\fIdmVODZ\fR;
.RS 4
Set to true when downloading lists of sent or received messages and a particular message is a high\-volume data message\&.
.RE
.PP
\%\fBlong int *\fR\%\fIattsNum\fR;
.RS 4
Set to number of attachments when downloading lists of sent or received messages and a particular message is a high\-volume data message\&.
.RE
.PP
Following members apply to outgoing messages only:
.PP
\%\fB_Bool *\fR\%\fIdmOVM\fR;
.RS 4
OVM sending mode\&. Non\-OVM dbType boxes that have dbEffectiveOVM equal to true
\fIMUST\fR
select between true (OVM mode) and false (non\-OVM mode)\&. Otherwise the value is optional and the default value is true\&.
.RE
.PP
\%\fB_Bool *\fR\%\fIdmPublishOwnID\fR;
.RS 4
To allow to reveal sender\*(Aqs login name\&. The name will be available to the recipient through
\%\fBisds_get_message_sender\fR
function\&. The sender\*(Aqs box type and identifier will be always available\&. This feature exists because more users can have access to one box and the recipient could not tell who was the sender\&. This value is optional\&. Default value is false\&.
.RE
.PP
\%\fBint *\fR\%\fIidLevel\fR;
.RS 4
Specifies which personal information about the sender should be revealed to the recipient\&. All specified information can be acquired by the recipient by using the
\%\fBisds_GetMessageAuthor2\fR
function\&. The sender\*(Aqs box type and identifier will always be available\&. The value of
\%\fIdmPublishOwnID\fR
\fIMUST\fR
be set to true in order to specify which additional information the sender wants to disclose\&. The actual value of the
\%\fIidLevel\fR
is the sum of actual
\%\fBenum isds_IdLevel_value\fR
values\&.
.RE
.SS "\%isds_FileMetaType"
.sp
.if n \{\
.RS 4
.\}
.nf
typedef enum \%\fBisds_FileMetaType\fR;
.fi
.if n \{\
.RE
.\}
.sp
.PP
Document type from point of view of hierarchy of documents in a message\&. Known values are:
.PP
\%\fBFILEMETATYPE_MAIN\fR
.RS 4
Main document\&. There should be exactly one document of this type in a message\&.
.RE
.PP
\%\fBFILEMETATYPE_ENCLOSURE\fR
.RS 4
An appendix\&. If a message has more documents, generic\-purpose documents other than the main one should have this type\&.
.RE
.PP
\%\fBFILEMETATYPE_SIGNATURE\fR
.RS 4
Digital signature\&. This document is a signature of another document in the message\&.
.RE
.PP
\%\fBFILEMETATYPE_META\fR
.RS 4
XML
document for
electronic document information system,
elektronická spisová služba
(ESS) in Czech, purpose\&.
.RE
.SS "struct isds_document"
.sp
.if n \{\
.RS 4
.\}
.nf
struct isds_document;
.fi
.if n \{\
.RE
.\}
.sp
.PP
A message document\&. Members are:
.PP
\%\fB_Bool\fR \%\fIis_xml\fR;
.RS 4
True if the document is an
ISDS
XML
document\&. False if the document is an
ISDS
binary document\&.
.RE
.PP
\%\fBxmlNodePtr\fR \%\fIxml_node_list\fR;
.RS 4
XML
node\-set presenting the
XML
document content\&. This is a pointer to first
XML
node of the
XML
representation of the message as stored in
\%\fIxml\fR
member of
\%\fBisds_message\fR
structure\&. Use
\%\fIchildren\fR
and
\%\fInext\fR
members to walk through the document\&. See
libxml2
library documentation for more details\&. The
\%\fIxml_node_list\fR
will be
\%\fBNULL\fR
if the document is empty\&. It\*(Aqs valid only if the
\%\fIis_xml\fR
is true\&.
.RE
.PP
\%\fBvoid *\fR\%\fIdata\fR;
.RS 4
A binary document content\&. The encoding and format depends on
\%\fIdmMimeType\fR
member value\&. This is valid only if the
\%\fIis_xml\fR
is false\&.
.RE
.PP
\%\fBsize_t\fR \%\fIdata_length\fR;
.RS 4
Length of the
\%\fIdata\fR
buffer in bytes\&. It\*(Aqs valid only if the
\%\fIis_xml\fR
is false\&.
.RE
.PP
\%\fBchar *\fR\%\fIdmMimeType\fR;
.RS 4
MIME
type of document\&. This member is mandatory\&.
.RE
.PP
\%\fBisds_FileMetaType\fR \%\fIdmFileMetaType\fR;
.RS 4
Document type to create document hierarchy inside a message\&.
.RE
.PP
\%\fBchar *\fR\%\fIdmFileGuid\fR;
.RS 4
Message\-local document identifier\&. It can be used as a key to refer to this document by
\%\fIdmUpFileGuid\fR
member from a different document\&. This is optional\&.
.RE
.PP
\%\fBchar *\fR\%\fIdmUpFileGuid\fR;
.RS 4
A reference to upper document identifier stored in
\%\fIdmFileGuid\fR
member of different document\&. You can use
\%\fBisds_find_document_by_id\fR
function to locate the upper document\&. This value is optional\&.
.RE
.PP
\%\fBchar *\fR\%\fIdmFileDescr\fR;
.RS 4
Document name (title)\&.
E\&.g\&.
a file name\&. This value is mandatory\&.
.RE
.PP
\%\fBchar *\fR\%\fIdmFormat\fR;
.RS 4
A reference to
XML
format definition that explains how to interpret the
XML
document\&.
E\&.g\&.
a
URL
to an
XML
schema\&. This value is optional\&.
.RE
.SS "struct isds_box_state_period"
.sp
.if n \{\
.RS 4
.\}
.nf
struct isds_box_state_period;
.fi
.if n \{\
.RE
.\}
.sp
.PP
A box state valid in the time range\&. Members are:
.PP
\%\fBstruct isds_timeval *\fR\%\fIfrom\fR;
.RS 4
Time range beginning\&.
.RE
.PP
\%\fBstruct isds_timeval *\fR\%\fIto\fR;
.RS 4
Time range end\&.
.RE
.PP
\%\fBlong int \fR\%\fIdbState\fR;
.RS 4
Box state\&.
\%\fB1\fR
means the box is accessible\&. Other values mean the box is inaccessible\&. You can use
\%\fBisds_DbState\fR
enum to identify some states\&.
.RE
.SS "struct isds_dmMessageAuthor"
.sp
.if n \{\
.RS 4
.\}
.nf
struct isds_dmMessageAuthor;
.fi
.if n \{\
.RE
.\}
.sp
.PP
Response for GetMessageAuthor2\&. Members are:
.PP
\%\fBisds_sender_type *\fR\%\fIuserType\fR;
.RS 4
Message sender type\&.
.RE
.PP
\%\fBstruct isds_PersonName2 *\fR\%\fIpersonName\fR;
.RS 4
Contains pnGivenNames and pnLastName\&.
.RE
.PP
\%\fBstruct tm *\fR\%\fIbiDate\fR;
.RS 4
Date of birth in local time at birth place, only tm_year, tm_mon and tm_mday carry sane value\&.
.RE
.PP
\%\fBchar *\fR\%\fIbiCity\fR;
.RS 4
City of birth\&.
.RE
.PP
\%\fBchar *\fR\%\fIbiCounty\fR;
.RS 4
County of birth (German: Bezirk, Czech: okres)\&.
.RE
.PP
\%\fBchar *\fR\%\fIadCode\fR;
.RS 4
RUIAN address code\&.
.RE
.PP
\%\fBchar *\fR\%\fIfullAddress\fR;
.RS 4
Full address\&.
.RE
.PP
\%\fB_Bool *\fR\%\fIrobIdent\fR;
.RS 4
Flag whether the person is identifiers within the ROB\&.
.RE
.SS "\%enum isds_message_type"
.sp
.if n \{\
.RS 4
.\}
.nf
typedef enum isds_message_type \%\fBisds_message_type\fR;
.fi
.if n \{\
.RE
.\}
.sp
.PP
Specifies the direction of the message \- whether the message is received or sent:
.PP
\%\fBMESSAGE_TYPE_RECEIVED\fR
.RS 4
Specifies a received message\&.
.RE
.PP
\%\fBMESSAGE_TYPE_SENT\fR
.RS 4
Specifies a sent message\&.
.RE
.SS "\%enum isds_data_format"
.sp
.if n \{\
.RS 4
.\}
.nf
typedef enum isds_data_format \%\fBisds_data_format\fR;
.fi
.if n \{\
.RE
.\}
.sp
.PP
Specifies data format:
.PP
\%\fBFORMAT_XML\fR
.RS 4
Data in XML format\&.
.RE
.PP
\%\fBFORMAT_CSV\fR
.RS 4
Data in CSV format\&.
.RE
.SS "\%enum isds_asyncReqType"
.sp
.if n \{\
.RS 4
.\}
.nf
typedef enum isds_asyncReqType \%\fBisds_asyncReqType\fR;
.fi
.if n \{\
.RE
.\}
.sp
.PP
Specifies synchronous request type:
.PP
\%\fBASYNC_REQ_TYPE_LIST_ERASED\fR
.RS 4
Response for the GetListOfErasedMessages request\&.
.RE
.SS "struct isds_erased_message"
.sp
.if n \{\
.RS 4
.\}
.nf
struct isds_erased_message;
.fi
.if n \{\
.RE
.\}
.sp
.PP
Describes entries in the lists of erased messages\&. Members are:
.PP
\%\fBchar *\fR\%\fIdmID\fR;
.RS 4
Message ID\&.
.RE
.PP
\%\fBchar *\fR\%\fIdbIDSender\fR;
.RS 4
Box ID of sender\&.
.RE
.PP
\%\fBchar *\fR\%\fIdmSender\fR;
.RS 4
Sender name\&.
.RE
.PP
\%\fBchar *\fR\%\fIdbIDRecipient\fR;
.RS 4
Box ID of recipient\&.
.RE
.PP
\%\fBchar *\fR\%\fIdmRecipient\fR;
.RS 4
Recipient name\&.
.RE
.PP
\%\fBchar *\fR\%\fIdmAnnotation\fR;
.RS 4
Subject (title) of the message\&.
.RE
.PP
\%\fBenum isds_message_status *\fR\%\fIdmMessageStatus\fR;
.RS 4
Message state\&.
.RE
.PP
\%\fBstruct isds_timeval *\fR\%\fIdmDeliveryTime\fR;
.RS 4
Time of delivery into a box\&.
.RE
.PP
\%\fBstruct isds_timeval *\fR\%\fIdmAcceptanceTime\fR;
.RS 4
Time of acceptance of the message by a user\&.
.RE
.PP
\%\fBchar *\fR\%\fIdmType\fR;
.RS 4
Message type\&.
.RE
.SH "FUNCTIONS"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.ad l
.hy 0
.HP \w'const\ char\ *isds_strerror('u
.BI "const char *isds_strerror(const\ isds_error\ " "error" ");"
.ad
.hy
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.ad l
.hy 0
.HP \w'struct\ isds_ctx\ *isds_ctx_create('u
.BI "struct isds_ctx *isds_ctx_create(void);"
.ad
.hy
.RE
.SH "SEE ALSO"
.PP
\fBlibcurl\fR(3), \fBlibdatovka\fR(3), \fBtime.h\fR(0p)
.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