DATA TYPES¶
struct isds_ctx¶
Context for specific ISDS box.
isds_error¶
Error code. Known values:
IE_SUCCESS
No error. Numeric value 0.
IE_ERROR
Unspecified error.
IE_NOTSUP
Operation is not supported.
IE_INVAL
Invalid value.
IE_INVALID_CONTEXT
The context is not valid.
IE_NOT_LOGGED_IN
The context has not been logged in.
IE_CONNECTION_CLOSED
Network connection has been closed.
IE_TIMED_OUT
Time limit for network operation exceeded.
IE_NOEXIST
Requested entity does exist.
IE_NOMEM
Not enough memory.
IE_NETWORK
Network error.
IE_HTTP
Error on HTTP level.
IE_SOAP
Error on SOAP level.
IE_XML
Error on XML level.
IE_ISDS
Problem with ISDS server.
IE_ENUM
Invalid enum value.
IE_DATE
Invalid date value.
IE_2BIG
Value is too big.
IE_2SMALL
Value is too small.
IE_NOTUNIQ
Value is not uniq.
IE_NOTEQUAL
Compared values are not equal.
IE_PARTIAL_SUCCESS
Operaration on a vector succeded for some values, but
failed for others.
IE_ABORTED
Operation was aborted by application request.
IE_SECURITY
Security requirements were not satisfied.
isds_log_level¶
typedef enum isds_log_level;
Log level. Know values:
ILL_NONE
0
ILL_CRIT
10
ILL_ERR
20
ILL_WARNING
30
ILL_INFO
40
ILL_DEBUG
50
ILL_ALL
100
isds_log_facility¶
typedef enum isds_log_facility;
Log facility. Know values:
ILF_NONE
0x0
ILF_HTTP
0x1
ILF_SOAP
0x2
ILF_ISDS
0x4
ILF_FILE
0x8
ILF_SEC
0x10
ILF_XML
0x20
ILF_ALL
0xFF
isds_option¶
typedef enum isds_option;
libisds option identifiers. Known values:
IOPT_TLS_VERIFY_SERVER
Option type is _Bool. Whether to verify server
identity. Default value is true.
IOPT_TLS_CA_FILE
Option type is char *. Option value is a file name
with certificate authority certificates. Default value depends on used
cryptographic library.
IOPT_TLS_CA_DIRECTORY
Option type is char *, Option value is a directory
with certificate authority certificates. Default value depends on used
cryptographic library.
IOPT_TLS_CRL_FILE
Option type is char *. Option value is a file name
with certificat revocation list in PEM format. Default value depends on used
cryptographic library.
IOPT_NORMALIZE_MIME_TYPE
Optiona type is _Bool. Whether to normalize MIME
type values. Default value is false.
isds_tls_option¶
typedef enum isds_tls_option;
Warning
This type is deprecated.
TLS libisds option identifiers. Known values:
ITLS_VERIFY_SERVER
Option type is _Bool. Whether to verify server
identity.
ITLS_CA_FILE
Option type is char *. Option value is a file name
with certificate authority certificates.
ITLS_CA_DIRECTORY
Option type is char *. Option value is a directory
name with certificate authority certificates.
ITLS_CRL_FILE
Option type is char *. Option value is a file name
with certificate revocation list in PEM format.
typedef enum isds_pki_format;
Cryptographic material encoding. Known values:
PKI_FORMAT_PEM
PEM format.
PKI_FORMAT_DER
DER format.
PKI_FORMAT_ENG
The material is stored in a cryptographic engine.
struct isds_pki_credentials¶
struct isds_pki_credentials;
This structure holds public key infrastructure cryptographic
material to authenticate a client. Members are:
char *engine;
String identifier of cryptographic engine to use (where
key is stored). Use NULL for no engine.
isds_pki_format certificate_format;
Certificate format.
char *certificate;
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 cryptographinc engines can pair certificate with key
automatically (NULL value).
isds_pki_format key_format;
Private key format.
char *key;
A path to client private key, or key identifier in case
an engine is used.
char *passphrase;
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.
isds_otp_method¶
typedef enum isds_otp_method;
One-time password authentication method. Known values:
OTP_HMAC
HMAC-based OTP method.
OTP_TIME
Time-based OTP method.
isds_otp_resolution¶
typedef enum isds_otp_resolution;
One-time password authentication resolution. Known values:
OTP_RESOLUTION_SUCCESS
Authentication succeded.
OTP_RESOLUTION_UNKNOWN
Status is unkown.
OTP_RESOLUTION_BAD_AUTHENTICATION
Bad log-in. You can retry to log in.
OTP_RESOLUTION_ACCESS_BLOCKED
Access blocked for 60 minutes. (Because a brute force
attack was detected.)
OTP_RESOLUTION_PASSWORD_EXPIRED
Password has expired.
Note
It's not clear which password expired: OTP or regular password?
OTP_RESOLUTION_TO_FAST
OTP cannot be sent repeatedly at this rate. (Minimal
delay depends on TOTP window setting.)
OTP_RESOLUTION_UNAUTHORIZED
User name is not allowed to access requested URI.
OTP_RESOLUTION_TOTP_SENT
OTP has been generated and sent by the ISDS to the
user.
OTP_RESOLUTION_TOTP_NOT_SENT
OTP could not been sent by the ISDS. Retry later.
struct isds_otp¶
This structure holds one-time password when authenticating a
client and resolution of the authentication.
Input members are:
isds_otp_method method;
Select OTP method to use.
char *otp_code;
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.)
Output members are:
isds_otp_resolution resolution;
Fine-grade resolution of this OTP authentication
attempt.
isds_DbType¶
typedef enum isds_DbType;
Box type. It classifies box owner by his legal status. Known
values:
DBTYPE_OVM_MAIN
This is a special value for
isds_find_box_by_fulltext. It's not accepted by any other
services.
DBTYPE_SYSTEM
This is a special value for sender of messages sent by
the ISDS. You can find it only in incomming messages. It's not accepted by any
other services.
DBTYPE_OVM
Standard government (state or municipality or similar)
office.
DBTYPE_OVM_NOTAR
Notary (stopped being used, replaced with OVM_PFO).
DBTYPE_OVM_EXEKUT
Executor (stopped being used, replaced with
OVM_PFO).
DBTYPE_OVM_REQ
Subsidiary office with OVM (governing) status assigned on
request (section 6 and 7 of the act).
DBTYPE_OVM_FO
Natural person with OVM status (without identification
number).
DBTYPE_OVM_PFO
Natural person in business with OVM status (e.g. notary
or executor).
DBTYPE_OVM_PO
Juridical person with OVM status (arisen from previously
existing PO or PO_REQ).
DBTYPE_PO
Standard commercial organization (listed in trade
registry).
DBTYPE_PO_ZAK
Other organization founded by an act (stopped being used,
replaced with PO).
DBTYPE_PO_REQ
An organization with a box assigned on its request.
DBTYPE_PFO
Person in business.
DBTYPE_PFO_ADVOK
Lawyer.
DBTYPE_PFO_DANPOR
Tax consultant.
DBTYPE_PFO_INSSPR
Administrator of insolvency.
DBTYPE_PFO_AUDITOR
Statutory auditor.
DBTYPE_FO
Standard person.
Some interfaces refer to gross 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.
isds_DbState¶
typedef enum isds_DbState;
Box status from point of view of accessibility. Known values:
DBSTATE_ACCESSIBLE
The box is accessible.
DBSTATE_TEMP_UNACCESSIBLE
The box is temporarily inaccessible (at the request of
the user).
DBSTATE_NOT_YET_ACCESSIBLE
The box has not yet been activated.
DBSTATE_PERM_UNACCESSIBLE
The box is permanently inaccessible.
DBSTATE_REMOVED
The box has been removed.
DBSTATE_TEMP_UNACCESSIBLE_LAW
The box is temporarily inaccessible (because of the
reasons enumerated in the law).
isds_priviledges¶
typedef enum isds_priviledges;
Distinct user permissions from point of view of ISDS. Instances
can be bitmaps of any of these distinct values. Distinct known values
are:
PRIVIL_READ_NON_PERSONAL
The user can download and read messages with
dmPersonalDelivery equaled to false.
PRIVIL_READ_ALL
The user can download and read messages with
dmPersonalDelivery equaled to true.
PRIVIL_CREATE_DM
The user can create and send messages, the user can
download outgoing (sent) messages.
PRIVIL_VIEW_INFO
The user can list messages and read data about a message
post and delivery.
PRIVIL_SEARCH_DB
The user can can search for boxes.
PRIVIL_OWNER_ADM
The user can administer his box (to add and remove
permitted users and to modify theirs permissions.)
PRIVIL_READ_VAULT
The user can read messages stored in the long term
storage.
Note
This permission is not used since 2012-05.
PRIVIL_ERASE_VAULT
The user can delete messages from the long term
storage.
isds_message_status¶
typedef enum isds_message_status;
Message status. Known values are:
MESSAGESTATE_SENT
The message has been put into ISDS.
MESSAGESTATE_STAMPED
Message was stamped by a time stamp authority.
MESSAGESTATE_INFECTED
The message included viruses. Infected documents have
been removed from the message.
MESSAGESTATE_DELIVERED
The message was delivered. (dmDeliveryTime is
populated.)
MESSAGESTATE_SUBSTITUTED
The message was delivered through fiction,
dmAcceptanceTime is populated.
MESSAGESTATE_RECEIVED
The message was accepted (by user's log-in or user's
explicit request). dmAcceptanceTime is populated.
MESSAGESTATE_READ
The message has been read by a user.
MESSAGESTATE_UNDELIVERABLE
The message could not been delivered. (E.g.The
recipient's box has been made inaccessible meantime.)
MESSAGESTATE_REMOVED
The message's content was deleted.
MESSAGESTATE_IN_SAFE
The message is stored in the long term storage.
The values can be combined into a bit mask for some functions. A
special MESSAGESTATE_ANY macro denotes any of the states.
isds_hash_algorithm¶
typedef enum isds_hash_algorithm;
Hash algorithm types. Known values are:
HASH_ALGORITHM_MD5
MD5.
HASH_ALGORITHM_SHA_1
SHA-1.
HASH_ALGORITHM_SHA_224
SHA-224.
HASH_ALGORITHM_SHA_256
SHA-256.
HASH_ALGORITHM_SHA_384
SHA-384.
HASH_ALGORITHM_SHA_512
SHA-256.
isds_buffer_strategy¶
typedef enum isds_buffer_strategy;
Buffer storage strategy. This type defines how a function should
embed application provided buffer into raw element of output
structure. Known values are:
BUFFER_DONT_STORE
Don't fill raw member.
BUFFER_COPY
Copy buffer content into newly allocated raw
member.
BUFFER_MOVE
Copy pointer. Leave deallocation to structure destructor
(isds_*_free()).
struct isds_hash¶
This is a hash value storage. Members are:
isds_hash_algorithm algorithm;
Hash algorithm.
size_t length;
Hash value length in bytes.
void *value;
Hash value as a byte stream.
struct isds_PersonName¶
Name of a person. Members are:
char *pnFirstName;
First name.
char *pnMiddleName;
Middle name.
char *pnLastName;
Current last name.
char *pnLastNameAtBirth;
Last name at birth.
struct isds_BirthInfo¶
Date and place of a birth. Members are:
struct tm *biDate;
Date of birth in local time at the birth place. Only
tm_year, tm_mon and tm_mday members of the struct
tm carry sane value. Others are undefined.
char *biCity;
City where a person was born.
char *biCounty;
Region where a person was born. This is the kind of
region that is called Bezirk in German and okres in Czech.
char *biState;
State wher a person was born.
struct isds_Address¶
Postal address. Members are:
char *adCity;
City.
char *adStreet;
Street.
char *adNumberInStreet;
Identification of an entrance on the street.
Číslo orientační in Czech.
char *adNumberInMunicipality;
Identification of a building in the municipality.
Číslo popisné in Czech.
char *adZipCode;
Postal code for mail routing.
char *adState;
State.
struct isds_DbOwnerInfo¶
Data about a box and his owner. NULL pointer values mean undefined
values. Members are:
char *dbID;
Box identifier. Specification limits the length to 7
characters.
isds_DbType *dbType;
Box type.
char *ic;
Identifier of the owner.
isds_PersonName *personName;
Name of a person owning the box.
char *firmName;
Name of a firm owning the box.
isds_BirthInfo *birthInfo;
Birth details of the person.
isds_Address *address;
Postal address of the owner.
char *nationality;
Nationality of the owner.
char *email;
E-mail addres of the owner.
char *telNumber;
Telephone number of the owner.
char *identifier;
External box identifier for data provider (OVM, PO, maybe
PFO box types.) Specification limits the length to 20 characters.
char *registryCode;
PFO external registry code. Specification limits the
length to 5 characters.
long int *dbState;
Box state. 1 means the box is active.
Note
The type is long int because specification declares it as
xsd:integer.
_Bool *dbEffectiveOVM;
The Box has OVM role (section 5a of the
act).
_Bool *dbOpenAddressing;
This non-OVM box is free to receive messages from
anybody.
isds_UserType¶
typedef enum isds_UserType;
User type. Known values are:
USERTYPE_PRIMARY
Owner of the box.
USERTYPE_ENTRUSTED
User with limited access to the box.
USERTYPE_ADMINISTRATOR
User who can manage USERTYPE_ENTRUSTED
users.
USERTYPE_OFFICIAL
???
USERTYPE_OFFICIAL_CERT
???
USERTYPE_LIQUIDATOR
Company liquidator.
USERTYPE_RECEIVER
Company receiver.
USERTYPE_GUARDIAN
Legal guardian.
struct isds_DbUserInfo¶
Data about a user. NULL pointer values mean undefined values.
Members are:
char *userID;
User identifier. Specification limits the length from 6
to 12 characters.
isds_UserType *userType;
User type.
long int *userPrivils;
Set of user permissions.
isds_PersonName *personName;
Name of the user.
isds_Address *address;
Postal address of the user.
struct tm *biDate;
Date of birth in local time. Only tm_year,
tm_mon and tm_mday members of the struct tm carry sane
value. Others are undefined.
char *ic;
Identifier a supervising firm. Specification limits the
length to 8 characters.
char *firmName;
Name of a supervising firm. Specification limits the
length to 100 characters.
char *caStreet;
Contact address. Street and number.
char *caCity;
Czech city of the contact address.
char *caZipCode;
Postal code of the contact address.
char *caState;
Abbreviated country of contact address. This value is
optional and implicit meaning is CZ.
isds_event_type¶
typedef enum isds_event_type;
Message event type. Known values are:
EVENT_UKNOWN
Event uknown to this library.
EVENT_ACCEPTED_BY_RECIPIENT
Message has been delivered and accepted by recipient
action.
EVENT_ACCEPTED_BY_FICTION
Message has been delivered, acceptance period timed out,
the message is considered as accepted.
EVENT_UNDELIVERABLE
Recipient box was made inaccessible, thus the message is
undeliverable.
EVENT_COMMERCIAL_ACCEPTED
Recipient confirmed acceptance of this commercial
message.
EVENT_ENTERED_SYSTEM
The message entered the ISDSsystem, i.e. it has been just
sent by a sender.
EVENT_DELIVERED
The message has been delivered into recipient's
box.
EVENT_PRIMARY_LOGIN
Primary user logged into recipent's box.
EVENT_ENTRUSTED_LOGIN
Entrusted user with capability to read logged into
recipient's box.
EVENT_SYSCERT_LOGIN
An application authenticated by system certificate
logged into recipient's box.
struct isds_event¶
An event that happened in a message life. All members are
optional. Members are:
struct timeval *time;
When the event occurred.
isds_event_type *type;
Type of the envent.
charr *description;
Human-readable event description generated by the ISDS
system. (Very probably in Czech language).
struct isds_envelope¶
Message envelope. These are the metadata about a message. It does
contain the message documents.
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.
Following members apply to incoming messages only:
char *dmID;
Message identifier. Maximal length is 20
characters.
char *dbIDSender;
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.
char *dmSender;
Sender's name. Maximal length is 100 characters.
char *dmSenderAddress;
Postal address of the sender. Maximal length is 100
characters.
long int *dmSenderType;
Gross box type of the sender. You can use
isds_DbType to enumarate 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.
char *dmRecipient;
Recipient's name. Maximal length is 100 characters.
char *dmRecipientAddress;
Postal address of the recipient. Maximal length is 100
characters.
_Bool *dmAmbiguousRecipient;
The recipient has OVM role.
Following members are assigned by the ISDS in different phases of
message life cycle:
unsigned long int *dmOrdinal;
Ordinal number in list of incoming/outgoing
messages.
isds_message_status *dmMessageStatus;
Message state.
long int *dmAttachmentSize;
Size of message documents in kilobytes. The value is
rounded.
struct timeval *dmDeliveryTime;
The time of delivering the message into recipient's box.
It will be NULL, if the message has not been delivered yet.
struct timeval *dmAcceptanceTime;
The time of acceptancing the message by the recipient. It
will be NULL, if message has not been accepted yet.
struct isds_hash *hash;
The message digest. This is a hash of a substring
representing isds:dmDM XML subtree. You can use
isds_compute_message_hash function to compute a hash of the message and
then compare it against this structure member using isds_hash_cmp
function.
void *timestamp;
This is a binary image of a qualified time stamp of the
hash value. The time stamp is provided by the ISDS system. Messages
that have not yet been stamped will have this value NULL.
size_t timestamp_length;
Length of the timestamp value in bytes.
struct isds_list *events;
Events the message passed trough. It's a list of
isds_event structures.
Following members apply to both outgoing and incoming
messages:
char *dmSenderOrgUnit;
Sender's organisation unit as a string. This is
optional.
long int *dmSenderOrgUnitNum;
Sender's organisation unit as a number. This is
optional.
char *dbIDRecipient;
Recipent's box identifier. This is mandatory. Maximal
length is 7 characters.
char *dmRecipientOrgUnit;
Recipient's organisation unit as a string. This is
optional.
long int *dmRecipientOrgUnitNum;
Recipent's organisation unit of as a number. This is
optional.
char *dmToHands;
A person in recipient's organisation. This is
optional.
char *dmAnnotation;
A subject (title) of the message. Maximal length is 255
characters.
char *dmRecipientRefNumber;
Czech: číslo jednací
příjemce. This is optional. Maximal length is 50
characters.
char *dmSenderRefNumber;
Czech: číslo jednací
odesílatele. This is optional. Maximal length is 50 chars.
char *dmRecipientIdent;
Czech: spisová značka
příjemce. This is optional. Maximal length is 50
characters.
char *dmSenderIdent;
Czech: spisová značka odesílatele
This is optional. Maximal length is 50 chars.
Following five members constitue a reference to an item from the
Czech Act Collection. The human-readable reference looks like Point
(Paragraph) § Section Law/Year Coll. The
memebers apply to both incoming and outgoing messages:
long int *dmLegalTitleLaw;
A number of an act mandating the authority.
long int *dmLegalTitleYear;
A year of issuing the act mandating the authority.
char *dmLegalTitleSect;
A section of the act mandating the authority. Czech:
paragraf.
char *dmLegalTitlePar;
A paragraph of the act mandating the authority. Czech:
odstavec.
char *dmLegalTitlePoint;
A point of the act mandating the authority. Czech:
písmeno.
Other incoming/outgoing message members:
_Bool *dmPersonalDelivery;
If true, only person with higher privileges can read this
message.
_Bool *dmAllowSubstDelivery;
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. Oonly OVM
dbType sender can set it.
char *dmType;
Message type (commercial subtypes or government message).
Input values (when sending the message):
"I"
A commercial message offering paying the response
(initiatory message). It's necessary to define dmSenderRefNumber
member.
"K"
A commercial message paid by the sender.
"O"
A commercial response paid by the sender of a initiatory
message. It's necessary to copy a value from the dmSenderRefNumber of
the initiatory message to the dmRecipientRefNumber of this
message.
"V"
A noncommercial government message. This is the default
meaning if the value is undefined while sending a message.
Output values (when retrieving the message):
"A"
This is a subsidized initiatory commercial message which
can pay a response.
"B"
This is a subsidized initiatory commercial message which
has already paid the response.
"C"
This is a subsidized initiatory commercial message where
the response offer has expired.
"D"
This is an externally subsidized commercial
messsage.
"E"
This is a commercial message prepaid by a stamp.
"G"
This is a commerical message paid by a sponsor.
"I"
See the input values.
"K"
See the input values.
"O"
See the input values.
"V"
See the input values.
"X"
This is an initiatory commercial message where the
response offer has expired.
"Y"
This is an initiatory commercial message which has
already paid the response.
"Z"
This is limitedly subsidized commercial message.
Length of the value is exactly 1 UTF-8 character if defined. That
means it's still zero-terminated character string.
Following members apply to outgoing messages only:
_Bool *dmOVM;
OVM sending mode. Non-OVM dbType boxes that have
dbEffectiveOVM equaled to true MUST select between true (OVM mode) and
false (non-OVM mode). Otherwise the value is optional and the default value is
true.
_Bool *dmPublishOwnID;
To allow to reveal sender's login name. The name will be
available to the recipient through isds_get_message_sender function.
The sender's 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.
typedef enum isds_FileMetaType;
Document type from point fo view of hierarchy of documents in a
message. Known values are:
FILEMETATYPE_MAIN
Main document. There should be exactly one document of
this type in a message.
FILEMETATYPE_ENCLOSURE
An appendix. If a message has more documents,
generic-purpose documents other than the main one should have this type.
FILEMETATYPE_SIGNATURE
Digital signature. This document is a signature of
another document in the message.
FILEMETATYPE_META
XML document for electronic document information system,
elektronická spisová služba (ESS) in Czech,
purpose.
struct isds_document¶
A message document. Members are:
_Bool is_xml;
True if the document is an ISDS XML document. False if
the document is an ISDS binary document.
xmlNodePtr xml_node_list;
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 xml member of isds_message structure. Use children and
next members to walk through the document. See libxml2 library
documentation for more details. The xml_node_list will be NULL
if the document is empty. It's valid only if the is_xml is true.
void *data;
A binary document content. The encoding and format
depends on dmMimeType member value. This is valid only if the
is_xml is false.
size_t data_length;
Length of the data buffer in bytes. It's valid
only if the is_xml is false.
char *dmMimeType;
MIME type of document. This member is mandatory.
isds_FileMetaType dmFileMetaType;
Document type to create document hierarchy inside a
message.
char *dmFileGuid;
Message-local document identifier. It can be used as a
key to refer to this document by dmUpFileGuid member from a different
document. This is optional.
char *dmUpFileGuid;
A reference to upper document identifier stored in
dmFileGuid member of different document. You can use
isds_find_document_by_id function to locate the upper document. This
value is optional.
char *dmFileDescr;
Document name (title). E.g. a file name. This value is
mandatory.
char *dmFormat;
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.
struct isds_box_state_period¶
struct isds_box_state_period;
A box state valid in the time range. Members are:
struct timeval *from;
Time range beginning.
struct timeval *to;
Time range end.
long int dbState;
Box state. 1 means the box is accessible. Other
values mean the box is inaccessible. You can use isds_DbState enum to
identify some states.