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