Implement ChangeISDSPassword as isds_change_password()
[libisds.git] / src / isds.h
blob6f39234529646f4b1b4eaf3b8235251b320e3f08
1 #ifndef __ISDS_ISDS_H__
2 #define __ISDS_ISDS_H__
4 /* Public interface for libisds.
5 * Private declarations in isds_priv.h. */
7 #include <stdlib.h> /* For size_t */
8 #include <sys/time.h> /* For struct timeval */
10 /* _deprecated macro marks library symbols as deprecated. Application should
11 * avoid using such function as soon as possible. */
12 #if defined(__GNUC__)
13 #define _deprecated __attribute__((deprecated))
14 #else
15 #define _deprecated
16 #endif
19 struct isds_ctx; /* Context for specific ISDS box */
21 typedef enum {
22 IE_SUCCESS = 0, /* No error, just for C conveniece (0 means Ok) */
23 IE_ERROR, /* Unspecified error */
24 IE_NOTSUP,
25 IE_INVAL,
26 IE_INVALID_CONTEXT,
27 IE_NOT_LOGGED_IN,
28 IE_CONNECTION_CLOSED,
29 IE_TIMED_OUT,
30 IE_NOEXIST,
31 IE_NOMEM,
32 IE_NETWORK,
33 IE_HTTP,
34 IE_SOAP,
35 IE_XML,
36 IE_ISDS,
37 IE_ENUM,
38 IE_DATE,
39 IE_2BIG,
40 IE_NOTUNIQ,
41 IE_NOTEQUAL,
42 IE_PARTIAL_SUCCESS
43 } isds_error;
45 typedef enum {
46 ILL_NONE = 0,
47 ILL_CRIT = 10,
48 ILL_ERR = 20,
49 ILL_WARNING = 30,
50 ILL_INFO = 40,
51 ILL_DEBUG = 50,
52 ILL_ALL = 100
53 } isds_log_level;
55 typedef enum {
56 ILF_NONE = 0x0,
57 ILF_HTTP = 0x1,
58 ILF_SOAP = 0x2,
59 ILF_ISDS = 0x4,
60 ILF_FILE = 0x8,
61 ILF_SEC = 0x10,
62 ILF_XML = 0x20,
63 ILF_ALL = 0xFF
64 } isds_log_facility;
66 /* Return text description of ISDS error */
67 const char *isds_strerror(const isds_error error);
69 /* TLS libisds options */
70 typedef enum {
71 ITLS_VERIFY_SERVER, /* _Bool: Verify server idetity? */
72 ITLS_CA_FILE, /* char *: File name with CA certificates */
73 ITLS_CA_DIRECTORY /* char *: Directory name with CA certificates */
74 } isds_tls_option;
76 /* Box type */
77 typedef enum {
78 DBTYPE_SYSTEM = 0, /* This is special sender value for messages
79 sent by ISDS. */
80 DBTYPE_OVM = 10,
81 DBTYPE_OVM_NOTAR = 11,
82 DBTYPE_OVM_EXEKUT = 12,
83 DBTYPE_OVM_REQ = 13,
84 DBTYPE_PO = 20,
85 DBTYPE_PO_ZAK = 21,
86 DBTYPE_PO_REQ = 22,
87 DBTYPE_PFO = 30,
88 DBTYPE_PFO_ADVOK = 31,
89 DBTYPE_PFO_DANPOR = 32,
90 DBTYPE_PFO_INSSPR = 33,
91 DBTYPE_FO = 40
92 } isds_DbType;
94 /* Box status from point of view of accesibilty */
95 typedef enum {
96 DBSTATE_ACCESSIBLE = 1,
97 DBSTATE_TEMP_UNACCESSIBLE = 2,
98 DBSTATE_NOT_YET_ACCESSIBLE = 3,
99 DBSTATE_PERM_UNACCESSIBLE = 4,
100 DBSTATE_REMOVED = 5
101 } isds_DbState;
103 /* User permissions from point of view of ISDS.
104 * Instances can be bitmas of any discrete values. */
105 typedef enum {
106 PRIVIL_READ_NON_PERSONAL = 0x1, /* Can download and read messages with
107 dmPersonalDelivery == false */
108 PRIVIL_READ_ALL = 0x2, /* Can download and read messages with
109 dmPersonalDelivery == true */
110 PRIVIL_CREATE_DM = 0x4, /* Can create and sent messages,
111 can dowload outgoing (sent) messages */
112 PRIVIL_VIEW_INFO = 0x8, /* Can list messages and data about
113 post and delivery */
114 PRIVIL_SEARCH_DB = 0x10, /* Can search for boxes */
115 PRIVIL_OWNER_ADM = 0x20 /* Can administer his box (add/remove
116 permitted users and theirs
117 permissions) */
118 } isds_priviledges;
120 /* Message status */
121 typedef enum {
122 MESSAGESTATE_SENT = 0x2, /* Message has been put into ISDS */
123 MESSAGESTATE_STAMPED = 0x4, /* Message stamped by TSA */
124 MESSAGESTATE_INFECTED = 0x8, /* Message included virues,
125 infected document has been removed */
126 MESSAGESTATE_DELIVERED = 0x10, /* Message delivered
127 (dmDeliveryTime stored) */
128 MESSAGESTATE_SUBSTITUTED = 0x20, /* Message delivered through fiction,
129 dmAcceptanceTime stored */
130 MESSAGESTATE_RECEIVED = 0x40, /* Message accepted (by user login or
131 user explicit request),
132 dmAcceptanceTime stored */
133 MESSAGESTATE_READ = 0x80, /* Message has been read by user */
134 MESSAGESTATE_UNDELIVERABLE = 0x100, /* Message could not been delivered
135 (e.g. recipent box has been made
136 unaccessible meantime) */
137 MESSAGESTATE_REMOVED = 0x200, /* Message content deleted */
138 MESSAGESTATE_IN_SAFE = 0x400 /* Message stored in data safe */
140 } isds_message_status;
141 #define MESSAGESTATE_ANY 0x7FE /* Union of all isds_message_status
142 values */
144 /* Hash algoritm types */
145 typedef enum {
146 HASH_ALGORITHM_MD5,
147 HASH_ALGORITHM_SHA_1,
148 HASH_ALGORITHM_SHA_256,
149 HASH_ALGORITHM_SHA_512,
150 } isds_hash_algorithm;
152 /* Buffer storage strategy.
153 * How function should embed application provided buffer into raw element of
154 * output structure. */
155 typedef enum {
156 BUFFER_DONT_STORE, /* Don't fill raw memeber */
157 BUFFER_COPY, /* Copy buffer content into newly allocated raw */
158 BUFFER_MOVE /* Just copy pointer.
159 But leave deallocation to isds_*_free(). */
160 } isds_buffer_strategy;
162 /* Hash value storage */
163 struct isds_hash {
164 isds_hash_algorithm algorithm; /* Hash algoritgm */
165 size_t length; /* Hash value lenght in bytes */
166 void *value; /* Hash value */
169 /* Name of person */
170 struct isds_PersonName {
171 char *pnFirstName;
172 char *pnMiddleName;
173 char *pnLastName;
174 char *pnLastNameAtBirth;
177 /* Date and place of birth */
178 struct isds_BirthInfo {
179 struct tm *biDate; /* Date of Birth in local time at birth place,
180 only tm_year, tm_mon and tm_mday carry sane
181 value */
182 char *biCity;
183 char *biCounty; /* German: Bezirk, Czech: okres */
184 char *biState;
187 /* Post address */
188 struct isds_Address {
189 char *adCity;
190 char *adStreet;
191 char *adNumberInStreet;
192 char *adNumberInMunicipality;
193 char *adZipCode;
194 char *adState;
197 /* Data about box and his owner.
198 * NULL pointer means undefined value */
199 struct isds_DbOwnerInfo {
200 char *dbID; /* Box ID */
201 isds_DbType *dbType; /* Box Type */
202 char *ic; /* ID */
203 struct isds_PersonName *personName; /* Name of person */
204 char *firmName; /* Name of firm */
205 struct isds_BirthInfo *birthInfo; /* Birth of person */
206 struct isds_Address *address; /* Post address */
207 char *nationality;
208 char *email;
209 char *telNumber;
210 char *identifier; /* External box identifier for data
211 provider (OVM, PO, maybe PFO)
212 [Max. 20 chars] */
213 char *registryCode; /* PFO External registry code
214 [Max. 5 chars] */
215 long int *dbState; /* Box state; 1 <=> active box;
216 long int beacause xsd:integer
217 TODO: enum? */
218 _Bool *dbEffectiveOVM; /* Box has OVM role (§ 5a) */
219 _Bool *dbOpenAddressing; /* Non-OVM Box is free to recieve
220 messages from anybody */
223 /* Message event type */
224 typedef enum {
225 EVENT_UKNOWN, /* Event unknown to this library */
226 EVENT_ACCEPTED_BY_RECIPIENT, /* Message has been delivered and accepted
227 by recipeint action */
228 EVENT_ACCEPTED_BY_FICTION, /* Message has been delivered, acceptance
229 timed out, considered as accepted */
230 EVENT_UNDELIVERABLE, /* Recipient box made unaccessible,
231 thus message is undelivarable */
232 EVENT_COMMERCIAL_ACCEPTED /* Recipient confirmed acceptace of
233 commercial message */
234 } isds_event_type;
236 /* Message event
237 * Alle members are optional as specification states so. */
238 struct isds_event {
239 struct timeval *time; /* When the event occurred */
240 isds_event_type *type; /* Type of the event */
241 char *description; /* Human readable event description
242 generated by ISDS (Czech) */
245 /* Message envelope
246 * Be ware that the string length contraints are forced only on output
247 * memebers transmitted to ISDS. The other direction (downloded from ISDS)
248 * can break these rules. It should not happen, but nobody knows how much
249 * incompatible new version of ISDS protocol will be. This is the gold
250 * Internet rule: be strict on what you put, be tollerant on what you get. */
251 struct isds_envelope {
252 /* Following memebers apply to incoming messages only: */
253 char *dmID; /* Message ID.
254 Maximal length is 20 characters. */
255 char *dbIDSender; /* Box ID of sender.
256 Special value "aaaaaaa" means sent by
257 ISDS.
258 Maximal length is 7 characters. */
259 char *dmSender; /* Sender name;
260 Maximal length is 100 characters. */
261 char *dmSenderAddress; /* Postal address of sender;
262 Maximal length is 100 characters. */
263 long int *dmSenderType; /* Gross Box type of sender
264 TODO: isds_DbType ? */
265 char *dmRecipient; /* Recipient name;
266 Maximal length is 100 characters. */
267 char *dmRecipientAddress; /* Postal address of recipient;
268 Maximal length is 100 characters. */
269 _Bool *dmAmbiguousRecipient; /* Recipient has OVM role */
270 char *dmType; /* Message type:
271 "V" is public message
272 "K" is commercial message */
274 /* Following memebers are assigned by ISDS in different phases of message
275 * life cycle. */
276 unsigned long int *dmOrdinal; /* Ordinal number in list of
277 incoming/outgoing messages */
278 isds_message_status *dmMessageStatus; /* Message state */
279 long int *dmAttachmentSize; /* Size of message documents in
280 kilobytes (rounded). */
281 struct timeval *dmDeliveryTime; /* Time of delivery into a box
282 NULL, if message has not been
283 delivered yet */
284 struct timeval *dmAcceptanceTime; /* Time of accpetance of the message
285 by an user. NULL if message has not
286 been accepted yet. */
287 struct isds_hash *hash; /* Message hash.
288 This is hash of isds:dmDM subtree. */
289 void *timestamp; /* Qualified time stamp */
290 size_t timestamp_length; /* Lenght of timestamp in bytes */
291 struct isds_list *events; /* Events message passed trough;
292 List of isds_event's. */
295 /* Following members apply to both outgoing and incoming messages: */
296 char *dmSenderOrgUnit; /* Organisation unit of sender as string;
297 Optional. */
298 long int *dmSenderOrgUnitNum; /* Organisation unit of sender as number;
299 Optional. */
300 char *dbIDRecipient; /* Box ID of recipient; Mandatory.
301 Maximal length is 7 characters. */
302 char *dmRecipientOrgUnit; /* Organisation unit of recipient as
303 string; Optional. */
304 long int *dmRecipientOrgUnitNum; /* Organisation unit of recipient as
305 number; Optional. */
306 char *dmToHands; /* Person in recipient organisation;
307 Optional. */
308 char *dmAnnotation; /* Subject (title) of the message.
309 Maximal length is 255 characters. */
310 char *dmRecipientRefNumber; /* Czech: číslo jednací příjemce; Optional.
311 Maximal length is 50 characters. */
312 char *dmSenderRefNumber; /* Czech: číslo jednací odesílatele;
313 Optional. Maximal lenght is 50 chars. */
314 char *dmRecipientIdent; /* Czech: spisová značka příjemce; Optional.
315 Maximal length is 50 characters. */
316 char *dmSenderIdent; /* Czech: spisová značka odesílatele;
317 Optional. Maximal lenght is 50 chars. */
319 /* Act addressing in Czech Republic:
320 * Point (Parahraph) § Section Law/Year Coll. */
321 long int *dmLegalTitleLaw; /* Number of act mandating authority */
322 long int *dmLegalTitleYear; /* Year of act issue mandating authority */
323 char *dmLegalTitleSect; /* Section of act mandating authority.
324 Czech: paragraf */
325 char *dmLegalTitlePar; /* Parahraph of act mandating authority.
326 Czech: odstavec */
327 char *dmLegalTitlePoint; /* Point of act mandating authority.
328 Czech: písmeno */
330 _Bool *dmPersonalDelivery; /* If true, only person with higher
331 priviledges can read this message */
332 _Bool *dmAllowSubstDelivery; /* Allow delivery through fiction.
333 I.e. Even if recipient did not read this
334 message, message is considered as
335 delivered after (currently) 10 days.
336 This is delivery through fiction.
337 Applies only to OVM dbType sender. */
338 _Bool *dmOVM; /* OVM sending mode.
339 Non-OVM dbType boxes that has
340 dbEffectiveOVM == true MUST select
341 between true (OVM mode) and
342 false (non-OVM mode).
343 Optionable; Implicit value is true. */
347 /* Document type from point of hiearchy */
348 typedef enum {
349 FILEMETATYPE_MAIN, /* Main document */
350 FILEMETATYPE_ENCLOSURE, /* Appendix */
351 FILEMETATYPE_SIGNATURE, /* Digital signature of other document */
352 FILEMETATYPE_META /* XML document for ESS (electronic
353 document information system) purposes */
354 } isds_FileMetaType;
356 /* Document */
357 struct isds_document {
358 void *data; /* Document content.
359 The encoding and interpretation depends
360 on dmMimeType.
361 TODO: inline XML */
362 size_t data_length; /* Length of the data in bytes */
363 char *dmMimeType; /* MIME type of data; Mandatory. */
364 isds_FileMetaType dmFileMetaType; /* Document type to create hierarchy */
365 char *dmFileGuid; /* Message-local document identifier;
366 Optional. */
367 char *dmUpFileGuid; /* Reference to upper document identifier
368 (dmFileGuid); Optional. */
369 char *dmFileDescr; /* Document name (title). E.g. file name;
370 Mandatory. */
371 char *dmFormat; /* Reference to XML form definition;
372 Defines howto interpret XML document;
373 Optional. */
376 /* Raw message representation content type.
377 * This is necessary to distinguish between different representations without
378 * expensive repated detection.
379 * Infix explanation:
380 * PLAIN_SIGNED data are XML with namespace mangled to signed alternative
381 * CMS_SIGNED data are XML with signed namespace encapsulated in CMS */
382 typedef enum {
383 RAWTYPE_INCOMING_MESSAGE,
384 RAWTYPE_PLAIN_SIGNED_INCOMING_MESSAGE,
385 RAWTYPE_CMS_SIGNED_INCOMING_MESSAGE,
386 RAWTYPE_PLAIN_SIGNED_OUTGOING_MESSAGE,
387 RAWTYPE_CMS_SIGNED_OUTGOING_MESSAGE,
388 RAWTYPE_DELIVERYINFO,
389 RAWTYPE_PLAIN_SIGNED_DELIVERYINFO,
390 RAWTYPE_CMS_SIGNED_DELIVERYINFO
391 } isds_raw_type;
393 /* Message */
394 struct isds_message {
395 void *raw; /* Raw message in XML format as send to or
396 from the ISDS. You can use it to store
397 local copy. This is binary buffer. */
398 size_t raw_length; /* Lenght of raw message in bytes */
399 isds_raw_type raw_type; /* Content type of raw representation
400 Meaningfull only with non-NULL raw
401 member */
402 struct isds_envelope *envelope; /* Message envelope */
403 struct isds_list *documents; /* List of isds_document's.
404 Valid message must contain exactly one
405 document of type FILEMETATYPE_MAIN and
406 can contain any number of other type
407 documents. Totol size of documents
408 must not exceed 10 MB. */
411 /* Message copy recipient and assigned message ID */
412 struct isds_message_copy {
413 /* Input members defined by application */
414 char *dbIDRecipient; /* Box ID of recipient; Mandatory.
415 Maximal length is 7 characters. */
416 char *dmRecipientOrgUnit; /* Organisation unit of recipient as
417 string; Optional. */
418 long int *dmRecipientOrgUnitNum; /* Organisation unit of recipient as
419 number; Optional. */
420 char *dmToHands; /* Person in recipient organisation;
421 Optional. */
423 /* Output members returned from ISDS */
424 isds_error error; /* libisds compatible error of delivery to o ne recipient */
425 char *dmStatus; /* Error description returned by ISDS;
426 Optional. */
427 char *dmID; /* Assigned message ID; Meaningfull only
428 for error == IE_SUCCESS */
431 /* General linked list */
432 struct isds_list {
433 struct isds_list *next; /* Next list item,
434 or NULL if current is last */
435 void *data; /* Payload */
436 void (*destructor) (void **); /* Payload deallocator */
439 /* Free isds_list with all member data.
440 * @list list to free, on return will be NULL */
441 void isds_list_free(struct isds_list **list);
444 /* Initialize ISDS library.
445 * Global function, must be called before other functions.
446 * If it failes you can not use ISDS library and must call isds_cleanup() to
447 * free partially inititialized global variables. */
448 isds_error isds_init(void);
450 /* Deinicialize ISDS library.
451 * Global function, must be called as last library function. */
452 isds_error isds_cleanup(void);
454 /* Create ISDS context.
455 * Each context can be used for different sessions to (possibly) different
456 * ISDS server with different credentials.
457 * Returns new context, or NULL */
458 struct isds_ctx *isds_ctx_create(void);
460 /* Destroy ISDS context and free memmory.
461 * @context will be NULLed on success. */
462 isds_error isds_ctx_free(struct isds_ctx **context);
464 /* Return long message text produced by library fucntion, e.g. detailed error
465 * mesage. Returned pointer is only valid until new library function is
466 * called for the same context. Could be NULL, especially if NULL context is
467 * supplied. Return string is locale encoded. */
468 char *isds_long_message(const struct isds_ctx *context);
470 /* Set logging up.
471 * @facilities is bitmask of isds_log_facility values,
472 * @level is verbosity level. */
473 void isds_set_logging(const unsigned int facilities,
474 const isds_log_level level);
477 /* Set timeout in miliseconds for each network job like connecting to server
478 * or sending message. Use 0 to disable timeout limits. */
479 isds_error isds_set_timeout(struct isds_ctx *context,
480 const unsigned int timeout);
482 /* Function provided by application libsds will call with
483 * following five arguments. Value zero of any argument means the value is
484 * unknown.
485 * @upload_total is expected total upload,
486 * @upload_current is cumulative current upload progress
487 * @dowload_total is expected total download
488 * @download_current is cumulative current download progress
489 * @data is pointer that will be passed unchanged to this function at run-time
490 * @return 0 to continue HTTP transfaer, or non-zero to abort transfer */
491 typedef int (*isds_progress_callback)(
492 double upload_total, double upload_current,
493 double download_total, double download_current,
494 void *data);
496 /* Register callback function libisds calls periodocally during HTTP data
497 * transfer.
498 * @context is session context
499 * @callback is function provided by application libsds will call. See type
500 * defition for @callback argument explanation.
501 * @data is application specific data @callback gets as last argument */
502 isds_error isds_set_progress_callback(struct isds_ctx *context,
503 isds_progress_callback callback, void *data);
505 /* Change SSL/TLS settings.
506 * @context is context which setting vill be applied to
507 * @option is name of option. It determines the type of last argument. See
508 * isds_tls_option definition for more info.
509 * @... is value of new setting. Type is determined by @option
510 * */
511 isds_error isds_set_tls(struct isds_ctx *context, const isds_tls_option option,
512 ...);
514 /* Connect and log in into ISDS server.
515 * @url is address of ISDS web service
516 * @username is user name of ISDS user
517 * @password is user's secret password
518 * @certificate is NULL terminated string with PEM formated client's
519 * certificate. Use NULL if only password autentication should be performed.
520 * @key is private key for client's certificate as (base64 encoded?) NULL
521 * terminated string. Use NULL if only password autentication is desired.
522 * */
523 isds_error isds_login(struct isds_ctx *context, const char *url,
524 const char *username, const char *password,
525 const char *certificate, const char* key);
527 /* Log out from ISDS server and close connection. */
528 isds_error isds_logout(struct isds_ctx *context);
530 /* Verify connection to ISDS is alive and server is responding.
531 * Sent dumy request to ISDS and expect dummy response. */
532 isds_error isds_ping(struct isds_ctx *context);
534 /* Get data about logged in user and his box. */
535 isds_error isds_GetOwnerInfoFromLogin(struct isds_ctx *context,
536 struct isds_DbOwnerInfo **db_owner_info);
538 /* Get expiration time of current password
539 * @context is session context
540 * @expiration is automatically reallocated time when password expires, In
541 * case of error will be nulled. */
542 isds_error isds_get_password_expiration(struct isds_ctx *context,
543 struct timeval **expiration);
545 /* Change user password in ISDS.
546 * User must supply old password, new password will takes effect after some
547 * time, current session can continue. Password must fulfill some constraints.
548 * @context is session context
549 * @old_password is current password.
550 * @new_password is requested new password */
551 isds_error isds_change_password(struct isds_ctx *context,
552 const char *old_password, const char *new_password);
554 /* Find boxes suiting given criteria.
555 * @context is ISDS session context.
556 * @criteria is filter. You should fill in at least some members.
557 * @boxes is automatically reallocated list of isds_DbOwnerInfo structures,
558 * possibly empty. Input NULL or valid old structure.
559 * @return:
560 * IE_SUCCESS if search sucseeded, @boxes contains usefull data
561 * IE_NOEXIST if no such box exists, @boxes will be NULL
562 * IE_2BIG if too much boxes exist and server truncated the resuluts, @boxes
563 * contains still valid data
564 * other code if something bad happens. @boxes will be NULL. */
565 isds_error isds_FindDataBox(struct isds_ctx *context,
566 const struct isds_DbOwnerInfo *criteria,
567 struct isds_list **boxes);
569 /* Get status of a box.
570 * @context is ISDS session context.
571 * @box_id is UTF-8 encoded box identifier as zero terminated string
572 * @box_status is return value of box status.
573 * @return:
574 * IE_SUCCESS if box has been found and its status retrieved
575 * IE_NOEXIST if box is not known to ISDS server
576 * or other appropriate error.
577 * You can use isds_DbState to enumerate box status. However out of enum
578 * range value can be returned too. This is feature because ISDS
579 * specification leaves the set of values open.
580 * Be ware that status DBSTATE_REMOVED is signaled as IE_SUCCESS. That means
581 * the box has been deleted, but ISDS still lists its former existence. */
582 isds_error isds_CheckDataBox(struct isds_ctx *context, const char *box_id,
583 long int *box_status);
585 /* Send a message via ISDS to a recipent
586 * @context is session context
587 * @outgoing_message is message to send; Some memebers are mandatory (like
588 * dbIDRecipient), some are optional and some are irrelevant (especialy data
589 * about sender). Included pointer to isds_list documents must contain at
590 * least one document of FILEMETATYPE_MAIN. This is read-write structure, some
591 * members will be filled with valid data from ISDS. Exact list of write
592 * members is subject to change. Currently dmId is changed.
593 * @return ISDS_SUCCESS, or other error code if something goes wrong. */
594 isds_error isds_send_message(struct isds_ctx *context,
595 struct isds_message *outgoing_message);
597 /* Send a message via ISDS to a multiple recipents
598 * @context is session context
599 * @outgoing_message is message to send; Some memebers are mandatory,
600 * some are optional and some are irrelevant (especialy data
601 * about sender). Data about recipient will be substituted by ISDS from
602 * @copies. Included pointer to isds_list documents must
603 * contain at least one document of FILEMETATYPE_MAIN.
604 * @copies is list of isds_message_copy structures addressing all desired
605 * recipients. This is read-write structure, some members will be filled with
606 * valid data from ISDS (message IDs, error codes, error descriptions).
607 * @return
608 * ISDS_SUCCESS if all messages have been sent
609 * ISDS_PARTIAL_SUCCESS if sending of some messages has failed (failed and
610 * succesed messages can be identified by copies->data->error),
611 * or other error code if something other goes wrong. */
612 isds_error isds_send_message_to_multiple_recipients(struct isds_ctx *context,
613 const struct isds_message *outgoing_message,
614 struct isds_list *copies);
616 /* Get list of outgoing (already sent) messages.
617 * Any criterion argument can be NULL, if you don't care about it.
618 * @context is session context. Must not be NULL.
619 * @from_time is minimal time and date of message sending inclusive.
620 * @to_time is maximal time and date of message sending inclusive
621 * @dmSenderOrgUnitNum is the same as isds_envelope.dmSenderOrgUnitNum
622 * @status_filter is bit field of isds_message_status values. Use special
623 * value MESSAGESTATE_ANY to signal you don't care. (It's defined as union of
624 * all values, you can use bitwise arithmetic if you want.)
625 * @offset is index of first message we are interested in. First message is 1.
626 * Set to 0 (or 1) if you don't care.
627 * @number is maximal length of list you want to get as input value, outputs
628 * number of messages matching these criteria. Can be NULL if you don't care
629 * (applies to output value either).
630 * @messages is automatically reallocated list of isds_message's. Be ware that
631 * it returns only brief overview (envelope and some other fields) about each
632 * message, not the complete message. FIXME: Specify exact fields.
633 * The list is sorted by delivery time in ascending order.
634 * Use NULL if you don't care about the metadata (useful if you want to know
635 * only the @number). If you provide &NULL, list will be allocated on heap,
636 * if you provide pointer to non-NULL, list will be freed automacally at first.
637 * Also in case of error the list will be NULLed.
638 * @return IE_SUCCESS or appropriate error code. */
639 isds_error isds_get_list_of_sent_messages(struct isds_ctx *context,
640 const struct timeval *from_time, const struct timeval *to_time,
641 const long int *dmSenderOrgUnitNum, const unsigned int status_filter,
642 const unsigned long int offset, unsigned long int *number,
643 struct isds_list **messages);
645 /* Get list of incoming (addressed to you) messages.
646 * Any criterion argument can be NULL, if you don't care about it.
647 * @context is session context. Must not be NULL.
648 * @from_time is minimal time and date of message sending inclusive.
649 * @to_time is maximal time and date of message sending inclusive
650 * @dmSenderOrgUnitNum is the same as isds_envelope.dmSenderOrgUnitNum
651 * @status_filter is bit field of isds_message_status values. Use special
652 * value MESSAGESTATE_ANY to signal you don't care. (It's defined as union of
653 * all values, you can use bitwise arithmetic if you want.)
654 * @offset is index of first message we are interested in. First message is 1.
655 * Set to 0 (or 1) if you don't care.
656 * @number is maximal length of list you want to get as input value, outputs
657 * number of messages matching these criteria. Can be NULL if you don't care
658 * (applies to output value either).
659 * @messages is automatically reallocated list of isds_message's. Be ware that
660 * it returns only brief overview (envelope and some other fields) about each
661 * message, not the complete message. FIXME: Specify exact fields.
662 * Use NULL if you don't care about the metadata (useful if you want to know
663 * only the @number). If you provide &NULL, list will be allocated on heap,
664 * if you provide pointer to non-NULL, list will be freed automacally at first.
665 * Also in case of error the list will be NULLed.
666 * @return IE_SUCCESS or appropriate error code. */
667 isds_error isds_get_list_of_received_messages(struct isds_ctx *context,
668 const struct timeval *from_time, const struct timeval *to_time,
669 const long int *dmSenderOrgUnitNum, const unsigned int status_filter,
670 const unsigned long int offset, unsigned long int *number,
671 struct isds_list **messages);
673 /* Download incoming message envelope identified by ID.
674 * @context is session context
675 * @message_id is message identifier (you can get them from
676 * isds_get_list_of_received_messages())
677 * @message is automatically reallocated message retrieved from ISDS.
678 * It will miss documents per se. Use isds_get_received_message(), if you are
679 * interrested in documents (content) too.
680 * Returned hash and timestamp require documents to be verifiable. */
681 isds_error isds_get_received_envelope(struct isds_ctx *context,
682 const char *message_id, struct isds_message **message);
684 /* Download signed delivery infosheet of given message identified by ID.
685 * @context is session context
686 * @message_id is message identifier (you can get them from
687 * isds_get_list_of_{sent,received}_messages())
688 * @message is automatically reallocated message retrieved from ISDS.
689 * It will miss documents per se. Use isds_get_signed_received_message(),
690 * if you are interrested in documents (content). OTOH, only this function
691 * can get list events message has gone through. */
692 isds_error isds_get_signed_delivery_info(struct isds_ctx *context,
693 const char *message_id, struct isds_message **message);
695 /* Load delivery info of any format from buffer.
696 * @context is session context
697 * @raw_type advertises format of @buffer content. Only delivery info types
698 * are accepted.
699 * @buffer is DER encoded PKCS#7 structure with signed delivery info. You can
700 * retrieve such data from message->raw after calling
701 * isds_get_signed_delivery_info().
702 * @length is length of buffer in bytes.
703 * @message is automatically reallocated message parsed from @buffer.
704 * @strategy selects how buffer will be attached into raw isds_message member.
705 * */
706 isds_error isds_load_delivery_info(struct isds_ctx *context,
707 const isds_raw_type raw_type,
708 const void *buffer, const size_t length,
709 struct isds_message **message, const isds_buffer_strategy strategy);
711 /* Download delivery infosheet of given message identified by ID.
712 * @context is session context
713 * @message_id is message identifier (you can get them from
714 * isds_get_list_of_{sent,received}_messages())
715 * @message is automatically reallocated message retrieved from ISDS.
716 * It will miss documents per se. Use isds_get_received_message(), if you are
717 * interrested in documents (content). OTOH, only this function can get list
718 * events message has gone through. */
719 isds_error isds_get_delivery_info(struct isds_ctx *context,
720 const char *message_id, struct isds_message **message);
722 /* Deprecated: Use isds_load_message() instead. */
723 /* Load incoming message from buffer.
724 * @context is session context
725 * @buffer XML stream with unsigned message. You can retrieve such data from
726 * message->raw after calling isds_get_received_message().
727 * @length is length of buffer in bytes.
728 * @message is automatically reallocated message parsed from @buffer.
729 * @strategy selects how buffer will be attached into raw isds_message member.
730 * */
731 isds_error isds_load_received_message(struct isds_ctx *context,
732 const void *buffer, const size_t length,
733 struct isds_message **message, const isds_buffer_strategy strategy)
734 _deprecated;
736 /* Download incoming message identified by ID.
737 * @context is session context
738 * @message_id is message identifier (you can get them from
739 * isds_get_list_of_received_messages())
740 * @message is automatically reallocated message retrieved from ISDS */
741 isds_error isds_get_received_message(struct isds_ctx *context,
742 const char *message_id, struct isds_message **message);
744 /* Deprecated: Use isds_load_message() instead. */
745 /* Load signed message from buffer.
746 * @context is session context
747 * @outgoing is true if message is outgoing, false if message is incoming
748 * @buffer is DER encoded PKCS#7 structure with signed message. You can
749 * retrieve such data from message->raw after calling
750 * isds_get_signed{received,sent}_message().
751 * @length is length of buffer in bytes.
752 * @message is automatically reallocated message parsed from @buffer.
753 * @strategy selects how buffer will be attached into raw isds_message member.
754 * */
755 isds_error isds_load_signed_message(struct isds_ctx *context,
756 const _Bool outgoing, const void *buffer, const size_t length,
757 struct isds_message **message, const isds_buffer_strategy strategy)
758 _deprecated;
760 /* Load message of any type from buffer.
761 * @context is session context
762 * @raw_type defines content type of @buffer. Only message types are allowed.
763 * @buffer is message raw representation. Format (CMS, plain signed,
764 * message direction) is defined in @raw_type. You can retrieve such data
765 * from message->raw after calling isds_get_[signed]{received,sent}_message().
766 * @length is length of buffer in bytes.
767 * @message is automatically reallocated message parsed from @buffer.
768 * @strategy selects how buffer will be attached into raw isds_message member.
769 * */
770 isds_error isds_load_message(struct isds_ctx *context,
771 const isds_raw_type raw_type, const void *buffer, const size_t length,
772 struct isds_message **message, const isds_buffer_strategy strategy);
774 /* Download signed incoming message identified by ID.
775 * @context is session context
776 * @message_id is message identifier (you can get them from
777 * isds_get_list_of_received_messages())
778 * @message is automatically reallocated message retrieved from ISDS. The raw
779 * memeber will be filled with PKCS#7 structure in DER format. */
780 isds_error isds_get_signed_received_message(struct isds_ctx *context,
781 const char *message_id, struct isds_message **message);
783 /* Download signed outgoing message identified by ID.
784 * @context is session context
785 * @message_id is message identifier (you can get them from
786 * isds_get_list_of_sent_messages())
787 * @message is automatically reallocated message retrieved from ISDS. The raw
788 * memeber will be filled with PKCS#7 structure in DER format. */
789 isds_error isds_get_signed_sent_message(struct isds_ctx *context,
790 const char *message_id, struct isds_message **message);
792 /* Retrieve hash of message identified by ID stored in ISDS.
793 * @context is session context
794 * @message_id is message identifier
795 * @hash is automatically reallocated message hash downloaded from ISDS.
796 * Message must exist in system and must not be deleted. */
797 isds_error isds_download_message_hash(struct isds_ctx *context,
798 const char *message_id, struct isds_hash **hash);
800 /* Compute hash of message from raw representation and store it into envelope.
801 * Original hash structure will be destroyed in envelope.
802 * @context is session context
803 * @message is message carrying raw XML message blob
804 * @algorithm is desired hash algorithm to use */
805 isds_error isds_compute_message_hash(struct isds_ctx *context,
806 struct isds_message *message, const isds_hash_algorithm algorithm);
808 /* Compare two hashes.
809 * @h1 is first hash
810 * @h2 is another hash
811 * @return
812 * IE_SUCCESS if hashes equal
813 * IE_NOTUNIQ if hashes are comparable, but they don't equal
814 * IE_ENUM if not comparable, but both structures defined
815 * IE_INVAL if some of the structures are undefined (NULL)
816 * IE_ERROR if internal error occurs */
817 isds_error isds_hash_cmp(const struct isds_hash *h1,
818 const struct isds_hash *h2);
820 /* Check message has gone through ISDS by comparing message hash stored in
821 * ISDS and locally computed hash. You must provide message with valid raw
822 * member (do not use isds_load_message(..., BUFFER_DONT_STORE)).
823 * This is convenient wrapper for isds_download_message_hash(),
824 * isds_compute_message_hash(), and isds_hash_cmp() sequence.
825 * @context is session context
826 * @message is message with valid raw and envelope member; envelope->hash
827 * member will be changed during funcion run. Use envelope on heap only.
828 * @return
829 * IE_SUCCESS if message originates in ISDS
830 * IE_NOTEQUAL if message is unknown to ISDS
831 * other code for other errors */
832 isds_error isds_verify_message_hash(struct isds_ctx *context,
833 struct isds_message *message);
835 /* Mark message as read. This is a transactional commit function to acknoledge
836 * to ISDS the message has been downloaded and processed by client properly.
837 * @context is session context
838 * @message_id is message identifier. */
839 isds_error isds_mark_message_read(struct isds_ctx *context,
840 const char *message_id);
842 /* Mark message as received by recipient. This is applicable only to
843 * commercial message. There is no specified way how to distinguishe
844 * commercial message from government message yet. Government message is
845 * received automatically (by law), commenrcial message on recipient request.
846 * @context is session context
847 * @message_id is message identifier. */
848 isds_error isds_mark_message_received(struct isds_ctx *context,
849 const char *message_id);
851 /* Send bogus request to ISDS.
852 * Just for test purposes */
853 isds_error isds_bogus_request(struct isds_ctx *context);
855 /* Search for document by document ID in list of documents. IDs are compared
856 * as UTF-8 string.
857 * @documents is list of isds_documents
858 * @id is document identifier
859 * @return first matching document or NULL. */
860 const struct isds_document *isds_find_document_by_id(
861 const struct isds_list *documents, const char *id);
863 /* Deallocate structure isds_hash and NULL it.
864 * @hash hash to to free */
865 void isds_hash_free(struct isds_hash **hash);
867 /* Deallocate structure isds_DbOwnerInfo recursively and NULL it */
868 void isds_DbOwnerInfo_free(struct isds_DbOwnerInfo **db_owner_info);
870 /* Deallocate struct isds_event recursively and NULL it */
871 void isds_event_free(struct isds_event **event);
873 /* Deallocate struct isds_envelope recursively and NULL it */
874 void isds_envelope_free(struct isds_envelope **envelope);
876 /* Deallocate struct isds_document recursively and NULL it */
877 void isds_document_free(struct isds_document **document);
879 /* Deallocate struct isds_message recursively and NULL it */
880 void isds_message_free(struct isds_message **message);
882 /* Deallocate struct isds_message_copy recursively and NULL it */
883 void isds_message_copy_free(struct isds_message_copy **copy);
885 #endif