src/isds.h

   1 #ifndef __ISDS_ISDS_H__
   2 #define __ISDS_ISDS_H__
   3
   4 /* Public interface for libisds.
   5  * Private declarations in isds_priv.h. */
   6
   7 #include <stdlib.h> /* For size_t */
   8 #include <sys/time.h> /* For struct timeval */
   9
  10 struct isds_ctx;    /* Context for specific ISDS box */
  11
  12 typedef enum {
  13     IE_SUCCESS = 0, /* No error, just for C conveniece (0 means Ok) */
  14     IE_ERROR,       /* Unspecified error */
  15     IE_NOTSUP,
  16     IE_INVAL,
  17     IE_INVALID_CONTEXT,
  18     IE_NOT_LOGGED_IN,
  19     IE_CONNECTION_CLOSED,
  20     IE_TIMED_OUT,
  21     IE_NOEXIST,
  22     IE_NOMEM,
  23     IE_NETWORK,
  24     IE_HTTP,
  25     IE_SOAP,
  26     IE_XML,
  27     IE_ISDS,
  28     IE_ENUM,
  29     IE_DATE,
  30     IE_2BIG,
  31     IE_NOTUNIQ
  32 } isds_error;
  33
  34 typedef enum {
  35     ILL_NONE = 0,
  36     ILL_CRIT = 10,
  37     ILL_ERR = 20,
  38     ILL_WARNING = 30,
  39     ILL_INFO = 40,
  40     ILL_DEBUG = 50,
  41     ILL_ALL = 100
  42 } isds_log_level;
  43
  44 typedef enum {
  45     ILF_NONE = 0x0,
  46     ILF_HTTP = 0x1,
  47     ILF_SOAP = 0x2,
  48     ILF_ISDS = 0x4,
  49     ILF_FILE = 0x8,
  50     ILF_SEC  = 0x10,
  51     ILF_ALL  = 0xFF
  52 } isds_log_facility;
  53
  54 /* Return text description of ISDS error */
  55 char *isds_strerror(const isds_error error);
  56
  57 /* TLS libisds options */
  58 typedef enum {
  59     ITLS_VERIFY_SERVER,     /*  _Bool: Verify server idetity? */
  60     ITLS_CA_FILE,           /* char *: File name with CA certificates */
  61     ITLS_CA_DIRECTORY       /* char *: Directory name with CA certificates */
  62 } isds_tls_option;
  63
  64 /* Box type */
  65 typedef enum {
  66     DBTYPE_SYSTEM = 0,          /* This is special sender value for messages
  67                                    sent by ISDS. */
  68     DBTYPE_OVM = 10,
  69     DBTYPE_OVM_NOTAR = 11,
  70     DBTYPE_OVM_EXEKUT = 12,
  71     DBTYPE_OVM_REQ = 13,
  72     DBTYPE_PO = 20,
  73     DBTYPE_PO_ZAK = 21,
  74     DBTYPE_PO_REQ = 22,
  75     DBTYPE_PFO = 30,
  76     DBTYPE_PFO_ADVOK = 31,
  77     DBTYPE_PFO_DANPOR = 32,
  78     DBTYPE_PFO_INSSPR = 33,
  79     DBTYPE_FO = 40
  80 } isds_DbType;
  81
  82 /* Box status from point of view of accesibilty */
  83 typedef enum {
  84     DBSTATE_ACCESSIBLE = 1,
  85     DBSTATE_TEMP_UNACCESSIBLE = 2,
  86     DBSTATE_NOT_YET_ACCESSIBLE = 3,
  87     DBSTATE_PERM_UNACCESSIBLE = 4,
  88     DBSTATE_REMOVED = 5
  89 } isds_DbState;
  90
  91 /* User permissions from point of view of ISDS.
  92  * Instances can be bitmas of any discrete values. */
  93 typedef enum {
  94     PRIVIL_READ_NON_PERSONAL = 0x1, /* Can download and read messages with
  95                                        dmPersonalDelivery == false */
  96     PRIVIL_READ_ALL = 0x2,          /* Can download and read messages with
  97                                        dmPersonalDelivery == true */
  98     PRIVIL_CREATE_DM = 0x4,         /* Can create and sent messages,
  99                                        can dowload outgoing (sent) messages */
 100     PRIVIL_VIEW_INFO = 0x8,         /* Can list messages and data about
 101                                        post and delivery */
 102     PRIVIL_SEARCH_DB = 0x10,        /* Can search for boxes */
 103     PRIVIL_OWNER_ADM = 0x20         /* Can administer his box (add/remove
 104                                        permitted users and theirs
 105                                        permissions) */
 106 } isds_priviledges;
 107
 108 /* Message status */
 109 typedef enum {
 110     MESSAGESTATE_SENT = 0x2,            /* Message has been put into ISDS */
 111     MESSAGESTATE_STAMPED = 0x4,         /* Message stamped by TSA */
 112     MESSAGESTATE_INFECTED = 0x8,        /* Message included virues,
 113                                            infected document has been removed */
 114     MESSAGESTATE_DELIVERED = 0x10,      /* Message delivered
 115                                            (dmDeliveryTime stored) */
 116     MESSAGESTATE_SUBSTITUTED = 0x20,    /* Message delivered through fiction,
 117                                            dmAcceptanceTime stored */
 118     MESSAGESTATE_RECIEVED = 0x40,       /* Message devlivered by user login
 119                                            dmAcceptanceTime stored */
 120     MESSAGESTATE_READ = 0x80,           /* Message has been read by user */
 121     MESSAGESTATE_UNDELIVERABLE = 0x100, /* Message could not been delivered
 122                                            (e.g. recipent box has been made
 123                                            unaccessible meantime) */
 124     MESSAGESTATE_REMOVED = 0x200        /* Message content deleted */
 125
 126 } isds_message_status;
 127 #define MESSAGESTATE_ANY 0x3FE          /* Union of all isds_message_status
 128                                            values */
 129
 130 /* Hash algoritm types */
 131 typedef enum {
 132     HASH_ALGORITHM_MD5,
 133     HASH_ALGORITHM_SHA_1,
 134     HASH_ALGORITHM_SHA_256,
 135     HASH_ALGORITHM_SHA_512,
 136 } isds_hash_algorithm;
 137
 138 /* Hash value storage */
 139 struct isds_hash {
 140     isds_hash_algorithm algorithm;      /* Hash algoritgm */
 141     size_t length;                 /* Hash value lenght in bytes */
 142     void *value;                        /* Hash value */
 143 };
 144
 145 /* Name of person */
 146 struct isds_PersonName {
 147     char *pnFirstName;
 148     char *pnMiddleName;
 149     char *pnLastName;
 150     char *pnLastNameAtBirth;
 151 };
 152
 153 /* Date and place of birth */
 154 struct isds_BirthInfo {
 155     struct tm *biDate;      /* Date of Birth in local time at birth place,
 156                                only tm_year, tm_mon and tm_mday carry sane
 157                                value */
 158     char *biCity;
 159     char *biCounty;         /* German: Bezirk, Czech: okres */
 160     char *biState;
 161 };
 162
 163 /* Post address */
 164 struct isds_Address {
 165     char *adCity;
 166     char *adStreet;
 167     char *adNumberInStreet;
 168     char *adNumberInMunicipality;
 169     char *adZipCode;
 170     char *adState;
 171 };
 172
 173 /* Data about box and his owner.
 174  * NULL pointer means undefined value */
 175 struct isds_DbOwnerInfo {
 176     char *dbID;                     /* Box ID */
 177     isds_DbType *dbType;            /* Box Type */
 178     char *ic;                       /* ID */
 179     struct isds_PersonName *personName;     /* Name of person */
 180     char *firmName;                 /* Name of firm */
 181     struct isds_BirthInfo *birthInfo;       /* Birth of person */
 182     struct isds_Address *address;   /* Post address */
 183     char *nationality;
 184     char *email;
 185     char *telNumber;
 186     char *identifier;               /* External box identifier for data
 187                                        provider (OVM, PO, maybe PFO)
 188                                        [Max. 20 chars] */
 189     char *registryCode;             /* PFO External registry code
 190                                        [Max. 5 chars] */
 191     long int *dbState;              /* Box state; 1 <=> active box;
 192                                        long int beacause xsd:integer
 193                                        TODO: enum? */
 194     _Bool *dbEffectiveOVM;          /* Box has OVM role (§ 5a) */
 195     _Bool *dbOpenAddressing;        /* Non-OVM Box is free to recieve
 196                                        messages from anybody */
 197 };
 198
 199
 200 /* Message envelope
 201  * Be ware that the string length contraints are forced only on output
 202  * memebers transmitted to ISDS. The other direction (downloded from ISDS)
 203  * can break these rules. It should not happen, but nobody knows how much
 204  * incompatible new version of ISDS protocol will be. This is the gold
 205  * Internet rule: be strict on what you put, be tollerant on what you get. */
 206 struct isds_envelope {
 207     /* Following memebers apply to incoming messages only: */
 208     char *dmID;                     /* Message ID.
 209                                        Maximal length is 20 characters. */
 210     char *dbIDSender;               /* Box ID of sender.
 211                                        Special value "aaaaaaa" means sent by
 212                                        ISDS.
 213                                        Maximal length is 7 characters. */
 214     char *dmSender;                 /* Sender name;
 215                                        Maximal length is 100 characters. */
 216     char *dmSenderAddress;          /* Postal address of sender;
 217                                        Maximal length is 100 characters. */
 218     long int *dmSenderType;         /* Gross Box type of sender
 219                                        TODO: isds_DbType ? */
 220     char *dmRecipient;              /* Recipient name;
 221                                        Maximal length is 100 characters. */
 222     char *dmRecipientAddress;       /* Postal address of recipient;
 223                                        Maximal length is 100 characters. */
 224     _Bool *dmAmbiguousRecipient;    /* Recipient has OVM role */
 225
 226     /* Following memebers are assigned by ISDS in different phases of message
 227      * life cycle. */
 228     unsigned long int *dmOrdinal;   /* Ordinal number in list of
 229                                        incoming/outgoing messages */
 230     isds_message_status *dmMessageStatus;  /* Message state */
 231     long int *dmAttachmentSize;     /* Size of message documents in
 232                                        kilobytes (rounded). */
 233     struct timeval *dmDeliveryTime;     /* Time of delivery into a box
 234                                            NULL, if message has not been
 235                                            delivered yet */
 236     struct timeval *dmAcceptanceTime;   /* Time of accpetance of the message
 237                                            by an user. NULL if message has not
 238                                            been accepted yet. */
 239     struct isds_hash *hash;         /* Message hash.
 240                                        This is hash of isds:dmDM subtree. */
 241     void *timestamp;                /* Qualified time stamp */
 242     size_t timestamp_length;        /* Lenght of timestamp in bytes */
 243
 244
 245     /* Following members apply to both outgoing and incoming messages: */
 246     char *dmSenderOrgUnit;          /* Organisation unit of sender as string;
 247                                        Optional. */
 248     long int *dmSenderOrgUnitNum;   /* Organisation unit of sender as number;
 249                                        Optional. */
 250     char *dbIDRecipient;            /* Box ID of recipient; Mandatory.
 251                                        Maximal length is 7 characters. */
 252     char *dmRecipientOrgUnit;       /* Organisation unit of recipient as
 253                                        string; Optional. */
 254     long int *dmRecipientOrgUnitNum;    /* Organisation unit of recipient as
 255                                            number; Optional. */
 256     char *dmToHands;                /* Person in recipient organisation;
 257                                        Optional. */
 258     char *dmAnnotation;             /* Subject (title) of the message.
 259                                        Maximal length is 255 characters. */
 260     char *dmRecipientRefNumber;     /* Czech: číslo jednací příjemce; Optional.
 261                                        Maximal length is 50 characters. */
 262     char *dmSenderRefNumber;        /* Czech: číslo jednací odesílatele;
 263                                        Optional. Maximal lenght is 50 chars. */
 264     char *dmRecipientIdent;         /* Czech: spisová značka příjemce; Optional.
 265                                        Maximal length is 50 characters. */
 266     char *dmSenderIdent;            /* Czech: spisová značka odesílatele;
 267                                        Optional. Maximal lenght is 50 chars. */
 268
 269     /* Act addressing in Czech Republic:
 270      * Point (Parahraph) § Section Law/Year Coll. */
 271     long int *dmLegalTitleLaw;      /* Number of act mandating authority */
 272     long int *dmLegalTitleYear;     /* Year of act issue mandating authority */
 273     char *dmLegalTitleSect;         /* Section of act mandating authority.
 274                                        Czech: paragraf */
 275     char *dmLegalTitlePar;          /* Parahraph of act mandating authority.
 276                                        Czech: odstavec */
 277     char *dmLegalTitlePoint;        /* Point of act mandating authority.
 278                                        Czech: písmeno */
 279
 280     _Bool *dmPersonalDelivery;      /* If true, only person with higher
 281                                        priviledges can read this message */
 282     _Bool *dmAllowSubstDelivery;    /* Allow delivery through fiction.
 283                                        I.e. Even if recipient did not read this
 284                                        message, message is considered as
 285                                        delivered after (currently) 10 days.
 286                                        This is delivery through fiction.
 287                                        Applies only to OVM dbType sender. */
 288     _Bool *dmOVM;                   /* OVM sending mode.
 289                                        Non-OVM dbType boxes that has
 290                                        dbEffectiveOVM == true MUST select
 291                                        between true (OVM mode) and
 292                                        false (non-OVM mode).
 293                                        Optionable; Implicit value is true. */
 294 };
 295
 296
 297 /* Document type from point of hiearchy */
 298 typedef enum {
 299     FILEMETATYPE_MAIN,              /* Main document */
 300     FILEMETATYPE_ENCLOSURE,         /* Appendix */
 301     FILEMETATYPE_SIGNATURE,         /* Digital signature of other document */
 302     FILEMETATYPE_META               /* XML document for ESS (electronic
 303                                        document information system) purposes */
 304 } isds_FileMetaType;
 305
 306 /* Document */
 307 struct isds_document {
 308     void *data;                     /* Document content.
 309                                        The encoding and interpretation depends
 310                                        on dmMimeType.
 311                                        TODO: inline XML */
 312     size_t data_length;             /* Length of the data in bytes */
 313     char *dmMimeType;               /* MIME type of data; Mandatory. */
 314     isds_FileMetaType dmFileMetaType;   /* Document type to create hierarchy */
 315     char *dmFileGuid;               /* Message-local document identifier;
 316                                        Optional. */
 317     char *dmUpFileGuid;             /* Reference to upper document identifier
 318                                        (dmFileGuid); Optional. */
 319     char *dmFileDescr;              /* Document name (title). E.g. file name;
 320                                        Mandatory. */
 321     char *dmFormat;                 /* Reference to XML form definition;
 322                                        Defines howto interpret XML document;
 323                                        Optional. */
 324 };
 325
 326 /* Message */
 327 struct isds_message {
 328     void *raw;                      /* Raw message in XML format as send to or
 329                                        from the ISDS. You can use it to store
 330                                        local copy. This is binary buffer. */
 331     size_t raw_length;              /* Lenght of raw message in bytes */
 332     struct isds_envelope *envelope; /* Message envelope */
 333     struct isds_list *documents;    /* List of isds_document's.
 334                                        Valid message must contain exactly one
 335                                        document of type FILEMETATYPE_MAIN and
 336                                        can contain any number of other type
 337                                        documents. Totol size of documents
 338                                        must not exceed 10 MB. */
 339 };
 340
 341 /* General linked list */
 342 struct isds_list {
 343     struct isds_list *next;         /* Next list item,
 344                                        or NULL if current is last */
 345     void *data;                     /* Payload */
 346     void (*destructor) (void **);   /* Payload deallocator */
 347 };
 348
 349 /* Free isds_list with all member data.
 350  * @list list to free, on return will be NULL */
 351 void isds_list_free(struct isds_list **list);
 352
 353
 354 /* Initialize ISDS library.
 355  * Global function, must be called before other functions.
 356  * If it failes you can not use ISDS library and must call isds_cleanup() to
 357  * free partially inititialized global variables. */
 358 isds_error isds_init(void);
 359
 360 /* Deinicialize ISDS library.
 361  * Global function, must be called as last library function. */
 362 isds_error isds_cleanup(void);
 363
 364 /* Create ISDS context.
 365  * Each context can be used for different sessions to (possibly) different
 366  * ISDS server with different credentials.
 367  * Returns new context, or NULL */
 368 struct isds_ctx *isds_ctx_create(void);
 369
 370 /* Destroy ISDS context and free memmory.
 371  * @context will be NULLed on success. */
 372 isds_error isds_ctx_free(struct isds_ctx **context);
 373
 374 /* Return long message text produced by library fucntion, e.g. detailed error
 375  * mesage. Returned pointer is only valid until new library function is
 376  * called for the same context. Could be NULL, especially if NULL context is
 377  * supplied. Return string is locale encoded. */
 378 char *isds_long_message(const struct isds_ctx *context);
 379
 380 /* Set logging up.
 381  * @facilities is bitmask of isds_log_facility values,
 382  * @level is verbosity level. */
 383 void isds_set_logging(const unsigned int facilities,
 384         const isds_log_level level);
 385
 386 /* Connect to given url.
 387  * It just makes TCP connection to ISDS server found in @url hostname part. */
 388 /*int isds_connect(struct isds_ctx *context, const char *url);*/
 389
 390 /* Set timeout in miliseconds for each network job like connecting to server
 391  * or sending message. Use 0 to disable timeout limits. */
 392 isds_error isds_set_timeout(struct isds_ctx *context,
 393         const unsigned int timeout);
 394
 395
 396 /* Change SSL/TLS settings.
 397  * @context is context which setting vill be applied to
 398  * @option is name of option. It determines the type of last argument. See
 399  * isds_tls_option definition for more info.
 400  * @... is value of new setting. Type is determined by @option
 401  * */
 402 isds_error isds_set_tls(struct isds_ctx *context, const isds_tls_option option,
 403         ...);
 404
 405 /* Connect and log in into ISDS server.
 406  * @url is address of ISDS web service
 407  * @username is user name of ISDS user
 408  * @password is user's secret password
 409  * @certificate is NULL terminated string with PEM formated client's
 410  * certificate. Use NULL if only password autentication should be performed.
 411  * @key is private key for client's certificate as (base64 encoded?) NULL
 412  * terminated string. Use NULL if only password autentication is desired.
 413  * */
 414 isds_error isds_login(struct isds_ctx *context, const char *url,
 415         const char *username, const char *password,
 416         const char *certificate, const char* key);
 417
 418 /* Log out from ISDS server and close connection. */
 419 isds_error isds_logout(struct isds_ctx *context);
 420
 421 /* Verify connection to ISDS is alive and server is responding.
 422  * Sent dumy request to ISDS and expect dummy response. */
 423 isds_error isds_ping(struct isds_ctx *context);
 424
 425 /* Get data about logged in user and his box. */
 426 isds_error isds_GetOwnerInfoFromLogin(struct isds_ctx *context,
 427         struct isds_DbOwnerInfo **db_owner_info);
 428
 429 /* Find boxes suiting given criteria.
 430  * @context is ISDS session context.
 431  * @criteria is filter. You should fill in at least some memebers.
 432  * @boxes is automatically reallocated list of isds_DbOwnerInfo structures,
 433  * possibly empty. Input NULL or valid old structure.
 434  * @return:
 435  *  IE_SUCCESS if search sucseeded, @boxes contains usefull data
 436  *  IE_NOEXIST if no such box exists, @boxes will be NULL
 437  *  IE_2BIG if too much boxes exist and server truncated the resuluts, @boxes
 438  *      contains still valid data
 439  *  other code if something bad happens. @boxes will be NULL. */
 440 isds_error isds_FindDataBox(struct isds_ctx *context,
 441         const struct isds_DbOwnerInfo *criteria,
 442         struct isds_list **boxes);
 443
 444 /* Get status of a box.
 445  * @context is ISDS session context.
 446  * @box_id is UTF-8 encoded box identifier as zero terminated string
 447  * @box_status is return value of box status.
 448  * @return:
 449  *  IE_SUCCESS if box has been found and its status retrieved
 450  *  IE_NOEXIST if box is not known to ISDS server
 451  *  or other appropriate error.
 452  *  You can use isds_DbState to enumerate box status. However out of enum
 453  *  range value can be returned too. This is feature because ISDS
 454  *  specification leaves the set of values open.
 455  *  Be ware that status DBSTATE_REMOVED is signaled as IE_SUCCESS. That means
 456  *  the box has been deleted, but ISDS still lists its former existence. */
 457 isds_error isds_CheckDataBox(struct isds_ctx *context, const char *box_id,
 458         long int *box_status);
 459
 460 /* Send a message via ISDS to a recipent
 461  * @context is session context
 462  * @outgoing_message is message to send; Some memebers are mandatory (like
 463  * dbIDRecipient), some are optional and some are irrelevant (especialy data
 464  * about sender). Included pointer to isds_list documents must contain at
 465  * least one document of FILEMETATYPE_MAIN. This is read-write structure, some
 466  * members will be filled with valid data from ISDS. Exact list of write
 467  * members is subject to change. Currently dmId is changed.
 468  * @return ISDS_SUCCESS, or other error code if something goes wrong. */
 469 isds_error isds_send_message(struct isds_ctx *context,
 470         struct isds_message *outgoing_message);
 471
 472 /* Get list of outgoing (already sent) messages.
 473  * Any criterion argument can be NULL, if you don't care about it.
 474  * @context is session context. Must not be NULL.
 475  * @from_time is minimal time and date of message sending inclusive.
 476  * @to_time is maximal time and date of message sending inclusive
 477  * @dmSenderOrgUnitNum is the same as isds_envelope.dmSenderOrgUnitNum
 478  * @status_filter is bit field of isds_message_status values. Use special
 479  * value MESSAGESTATE_ANY to signal you don't care. (It's defined as union of
 480  * all values, you can use bitwise arithmetic if you want.)
 481  * @offset is index of first message we are interested in. First message is 1.
 482  * Set to 0 (or 1) if you don't care.
 483  * @number is maximal length of list you want to get as input value, outputs
 484  * number of messages matching these criteria. Can be NULL if you don't care
 485  * (applies to output value either).
 486  * @messages is automatically reallocated list of isds_message's. Be ware that
 487  * it returns only brief overview (envelope and some other fields) about each
 488  * message, not the complete message. FIXME: Specify exact fields.
 489  * The list is sorted by delivery time in ascending order.
 490  * Use NULL if you don't care about the metadata (useful if you want to know
 491  * only the @number). If you provide &NULL, list will be allocated on heap,
 492  * if you provide pointer to non-NULL, list will be freed automacally at first.
 493  * Also in case of error the list will be NULLed.
 494  * @return IE_SUCCESS or appropriate error code. */
 495 isds_error isds_get_list_of_sent_messages(struct isds_ctx *context,
 496         const struct timeval *from_time, const struct timeval *to_time,
 497         const long int *dmSenderOrgUnitNum, const unsigned int status_filter,
 498         const unsigned long int offset, unsigned long int *number,
 499         struct isds_list **messages);
 500
 501 /* Get list of incoming (addressed to you) messages.
 502  * Any criterion argument can be NULL, if you don't care about it.
 503  * @context is session context. Must not be NULL.
 504  * @from_time is minimal time and date of message sending inclusive.
 505  * @to_time is maximal time and date of message sending inclusive
 506  * @dmSenderOrgUnitNum is the same as isds_envelope.dmSenderOrgUnitNum
 507  * @status_filter is bit field of isds_message_status values. Use special
 508  * value MESSAGESTATE_ANY to signal you don't care. (It's defined as union of
 509  * all values, you can use bitwise arithmetic if you want.)
 510  * @offset is index of first message we are interested in. First message is 1.
 511  * Set to 0 (or 1) if you don't care.
 512  * @number is maximal length of list you want to get as input value, outputs
 513  * number of messages matching these criteria. Can be NULL if you don't care
 514  * (applies to output value either).
 515  * @messages is automatically reallocated list of isds_message's. Be ware that
 516  * it returns only brief overview (envelope and some other fields) about each
 517  * message, not the complete message. FIXME: Specify exact fields.
 518  * Use NULL if you don't care about the metadata (useful if you want to know
 519  * only the @number). If you provide &NULL, list will be allocated on heap,
 520  * if you provide pointer to non-NULL, list will be freed automacally at first.
 521  * Also in case of error the list will be NULLed.
 522  * @return IE_SUCCESS or appropriate error code. */
 523 isds_error isds_get_list_of_received_messages(struct isds_ctx *context,
 524         const struct timeval *from_time, const struct timeval *to_time,
 525         const long int *dmSenderOrgUnitNum, const unsigned int status_filter,
 526         const unsigned long int offset, unsigned long int *number,
 527         struct isds_list **messages);
 528
 529 /* Download incoming message envelope identified by ID.
 530  * @context is session context
 531  * @message_id is message identifier (you can get them from
 532  * isds_get_list_of_received_messages())
 533  * @message is automatically reallocated message retrieved from ISDS.
 534  * It will miss documents per se. Use isds_get_received_message(), if you are
 535  * interrested in documents (content) too.
 536  * Returned hash and timestamp require documents to be verifiable. */
 537 isds_error isds_get_received_envelope(struct isds_ctx *context,
 538         const char *message_id, struct isds_message **message);
 539
 540 /* Download incoming message identified by ID.
 541  * @context is session context
 542  * @message_id is message identifier (you can get them from
 543  * isds_get_list_of_received_messages())
 544  * @message is automatically reallocated message retrieved from ISDS */
 545 isds_error isds_get_received_message(struct isds_ctx *context,
 546         const char *message_id, struct isds_message **message);
 547
 548 /* Download signed incoming message identified by ID.
 549  * @context is session context
 550  * @message_id is message identifier (you can get them from
 551  * isds_get_list_of_received_messages())
 552  * @message is automatically reallocated message retrieved from ISDS. The raw
 553  * memeber will be filled with PKCS#7 structure in DER format. */
 554 isds_error isds_get_signed_received_message(struct isds_ctx *context,
 555         const char *message_id, struct isds_message **message);
 556
 557 /* Download signed outgoing message identified by ID.
 558  * @context is session context
 559  * @message_id is message identifier (you can get them from
 560  * isds_get_list_of_sent_messages())
 561  * @message is automatically reallocated message retrieved from ISDS. The raw
 562  * memeber will be filled with PKCS#7 structure in DER format. */
 563 isds_error isds_get_signed_sent_message(struct isds_ctx *context,
 564         const char *message_id, struct isds_message **message);
 565
 566 /* Retrieve hash of message identified by ID stored in ISDS.
 567  * @context is session context
 568  * @message_id is message identifier
 569  * @hash is automatically reallocated message hash downloaded from ISDS.
 570  * Message must exist in system and must not be deleted. */
 571 isds_error isds_download_message_hash(struct isds_ctx *context,
 572         const char *message_id, struct isds_hash **hash);
 573
 574 /* Compute hash of message from raw representation and store it into envelope.
 575  * Original hash structure will be destroyed in envelope.
 576  * @context is session context
 577  * @message is message carrying raw XML message blob
 578  * @algorithm is desired hash algorithm to use */
 579 isds_error isds_compute_message_hash(struct isds_ctx *context,
 580         struct isds_message *message, const isds_hash_algorithm algorithm);
 581
 582 /* Mark message as read. This is a transactional commit function to acknoledge
 583  * to ISDS the message has been downloaded and processed by client properly.
 584  * @context is session context
 585  * @message_id is message identifier. */
 586 isds_error isds_mark_message_read(struct isds_ctx *context,
 587         const char *message_id);
 588
 589 /* Send bogus request to ISDS.
 590  * Just for test purposes */
 591 isds_error isds_bogus_request(struct isds_ctx *context);
 592
 593 /* Search for document by document ID in list of documents. IDs are compared
 594  * as UTF-8 string.
 595  * @documents is list of isds_documents
 596  * @id is document identifier
 597  * @return first matching document or NULL. */
 598 const struct isds_document *isds_find_document_by_id(
 599         const struct isds_list *documents, const char *id);
 600
 601 /* Deallocate structure isds_hash and NULL it.
 602  * @hash  hash to to free */
 603 void isds_hash_free(struct isds_hash **hash);
 604
 605 /* Deallocate structure isds_DbOwnerInfo recursively and NULL it */
 606 void isds_DbOwnerInfo_free(struct isds_DbOwnerInfo **db_owner_info);
 607
 608 /* Deallocate struct isds_envelope recurisvely and NULL it */
 609 void isds_envelope_free(struct isds_envelope **envelope);
 610
 611 /* Deallocate struct isds_document recurisvely and NULL it */
 612 void isds_document_free(struct isds_document **document);
 613
 614 /* Deallocate struct isds_message recurisvely and NULL it */
 615 void isds_message_free(struct isds_message **message);
 616
 617 #endif