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