Request half of isds_CheckDataBox() implemented
[libisds.git] / src / isds.h
blob218e45b41a3633c14ccf56ec6e1f8bc16589abd4
1 #ifndef __ISDS_ISDS_H__
2 #define __ISDS_ISDS_H__
4 /* Public interface for libisds.
5 * Private declarations in isds_priv.h. */
7 struct isds_ctx; /* Context for specific ISDS box */
9 typedef enum {
10 IE_SUCCESS = 0, /* No error, just for C conveniece (0 means Ok) */
11 IE_ERROR, /* unsepcified error */
12 IE_NOTSUP,
13 IE_INVAL,
14 IE_INVALID_CONTEXT,
15 IE_NOT_LOGGED_IN,
16 IE_CONNECTION_CLOSED,
17 IE_TIMED_OUT,
18 IE_NOEXIST,
19 IE_NOMEM,
20 IE_NETWORK,
21 IE_SOAP,
22 IE_XML,
23 IE_ISDS,
24 IE_ENUM,
25 IE_DATE,
26 IE_2BIG
27 } isds_error;
29 typedef enum {
30 ILL_NONE = 0,
31 ILL_CRIT = 10,
32 ILL_ERR = 20,
33 ILL_WARNING = 30,
34 ILL_INFO = 40,
35 ILL_DEBUG = 50,
36 ILL_ALL = 100
37 } isds_log_level;
39 typedef enum {
40 ILF_NONE = 0x0,
41 ILF_HTTP = 0x1,
42 ILF_SOAP = 0x2,
43 ILF_ISDS = 0x4,
44 ILF_FILE = 0x8,
45 ILF_SEC = 0x10,
46 ILF_ALL = 0xFF
47 } isds_log_facility;
49 /* Return text description of ISDS error */
50 char *isds_strerror(const isds_error error);
52 /* Box type */
53 typedef enum {
54 DBTYPE_FO,
55 DBTYPE_PFO,
56 DBTYPE_PFO_ADVOK,
57 DBTYPE_PFO_DANPOR,
58 DBTYPE_PFO_INSSPR,
59 DBTYPE_PO,
60 DBTYPE_PO_ZAK,
61 DBTYPE_PO_REQ,
62 DBTYPE_OVM,
63 DBTYPE_OVM_NOTAR,
64 DBTYPE_OVM_EXEKUT,
65 DBTYPE_OVM_REQ
66 } isds_DbType;
68 /* Box status from point of view of accesibilty */
69 typedef enum {
70 DBSTATE_ACCESIBLE = 1,
71 DBSTATE_TEMP_UNACCESSIBLE = 2,
72 DBSTATE_NOT_YET_ACCESSIBLE = 3,
73 DBSTATE_PERM_UNACCESSIBLE = 4,
74 DBSTATE_REMOVED = 5
75 } isds_DbState;
77 /* Name of person */
78 struct isds_PersonName {
79 char *pnFirstName;
80 char *pnMiddleName;
81 char *pnLastName;
82 char *pnLastNameAtBirth;
85 /* Date and place of birth */
86 struct isds_BirthInfo {
87 struct tm *biDate; /* Date of Birth in local time at birth place,
88 only tm_year, tm_mon and tm_mday carry sane
89 value */
90 char *biCity;
91 char *biCounty; /* German: Bezirk, Czech: okres */
92 char *biState;
95 /* Post address */
96 struct isds_Address {
97 char *adCity;
98 char *adStreet;
99 char *adNumberInStreet;
100 char *adNumberInMunicipality;
101 char *adZipCode;
102 char *adState;
105 /* Data about box and his owner.
106 * NULL pointer means undefined value */
107 struct isds_DbOwnerInfo {
108 char *dbID; /* Box ID */
109 isds_DbType *dbType; /* Box Type */
110 char *ic; /* ID */
111 struct isds_PersonName *personName; /* Name of person */
112 char *firmName; /* Name of firm */
113 struct isds_BirthInfo *birthInfo; /* Birth of person */
114 struct isds_Address *address; /* Post address */
115 char *nationality;
116 char *email;
117 char *telNumber;
118 char *identifier; /* External box identifier for data
119 provider (OVM, PO, maybe PFO)
120 [Max. 20 chars] */
121 char *registryCode; /* PFO External registry code
122 [Max. 5 chars] */
123 long int *dbState; /* Box state; 1 <=> active box;
124 long int beacause xsd:integer
125 TODO: enum? */
126 _Bool *dbEffectiveOVM; /* Box has OVM role (§ 5a) */
127 _Bool *dbOpenAddressing; /* Non-OVM Box is free to recieve
128 messages from anybody */
131 /* General linked list */
132 struct isds_list {
133 struct isds_list *next; /* Next list item,
134 or NULL if current is last */
135 void *data; /* Payload */
136 void (*destructor) (void **); /* Payload deallocator */
139 /* Free isds_list with all member data.
140 * @list list to free, on return will be NULL */
141 void isds_list_free(struct isds_list **list);
143 /*struct isds_address {
144 struct isds_address *next;
145 char *box_id;
146 char *name;
149 struct isds_message {
150 struct isds_message *next;
151 struct isds_address *sender;
152 struct isds_address *recipient;
153 char *subject;
154 };*/
157 /* Initialize ISDS library.
158 * Global function, must be called before other functions.
159 * If it failes you can not use ISDS library and must call isds_cleanup() to
160 * free partially inititialized global variables. */
161 isds_error isds_init(void);
163 /* Deinicialize ISDS library.
164 * Global function, must be called as last library function. */
165 isds_error isds_cleanup(void);
167 /* Create ISDS context.
168 * Each context can be used for different sessions to (possibly) different
169 * ISDS server with different credentials.
170 * Returns new context, or NULL */
171 struct isds_ctx *isds_ctx_create(void);
173 /* Destroy ISDS context and free memmory.
174 * @context will be NULLed on success. */
175 isds_error isds_ctx_free(struct isds_ctx **context);
177 /* Return long message text produced by library fucntion, e.g. detailed error
178 * mesage. Returned pointer is only valid until new library function is
179 * called for the same context. Could be NULL, especially if NULL context is
180 * supplied. Return string is locale encoded. */
181 char *isds_long_message(const struct isds_ctx *context);
183 /* Set logging up.
184 * @facilities is bitmask of isds_log_facility values,
185 * @level is verbosity level. */
186 void isds_set_logging(const unsigned int facilities, const isds_log_level level);
188 /* Connect to given url.
189 * It just makes TCP connection to ISDS server found in @url hostname part. */
190 /*int isds_connect(struct isds_ctx *context, const char *url);*/
192 /* Set timeout in miliseconds for each network job like connecting to server
193 * or sending message. Use 0 to disable timeout limits. */
194 isds_error isds_set_timeout(struct isds_ctx *context, const unsigned int timeout);
196 /* Connect and log in into ISDS server.
197 * @url is address of ISDS web service
198 * @username is user name of ISDS user
199 * @password is user's secret password
200 * @certificate is NULL terminated string with PEM formated client's
201 * certificate. Use NULL if only password autentication should be performed.
202 * @key is private key for client's certificate as (base64 encoded?) NULL
203 * terminated string. Use NULL if only password autentication is desired.
204 * */
205 isds_error isds_login(struct isds_ctx *context, const char *url, const char *username,
206 const char *password, const char *certificate, const char* key);
208 /* Log out from ISDS server and close connection. */
209 isds_error isds_logout(struct isds_ctx *context);
211 /* Verify connection to ISDS is alive and server is responding.
212 * Sent dumy request to ISDS and expect dummy response. */
213 isds_error isds_ping(struct isds_ctx *context);
215 /* Get data about logged in user and his box. */
216 isds_error isds_GetOwnerInfoFromLogin(struct isds_ctx *context,
217 struct isds_DbOwnerInfo **db_owner_info);
219 /* Find boxes suiting given criteria.
220 * @context is ISDS session context.
221 * @criteria is filter. You should fill in at least some memebers.
222 * @boxes is automatically reallocated list of isds_DbOwnerInfo structures,
223 * possibly empty. Input NULL or valid old structure.
224 * @return:
225 * IE_SUCCESS if search sucseeded, @boxes contains usefull data
226 * IE_NOEXIST if no such box exists, @boxes will be NULL
227 * IE_2BIG if too much boxes exist and server truncated the resuluts, @boxes
228 * contains still valid data
229 * other code if something bad happens. @boxes will be NULL. */
230 isds_error isds_FindDataBox(struct isds_ctx *context,
231 const struct isds_DbOwnerInfo *criteria,
232 struct isds_list **boxes);
234 /* Get status of a box.
235 * @context is ISDS session context.
236 * @box_id is UTF-8 encoded box identifier as zero terminated string
237 * @box_status is return value of box status.
238 * @return:
239 * IE_SUCCESS if box has been found and its status retrieved
240 * IE_NOEXIST if box is not known to ISDS server
241 * or other appropriate error.
242 * You can use isds_DbState to enumerate box status. However out of enum
243 * range value can be returned too. This is feature because ISDS
244 * specification leaves the set of values open.
245 * Be ware that status DBSTATE_REMOVED is signaled as IE_SUCCESS. That means
246 * the box has been deleted, but ISDS still lists its former existence. */
247 isds_error isds_CheckDataBox(struct isds_ctx *context, const char *box_id,
248 long int *box_status);
250 /* Send bogus request to ISDS.
251 * Just for test purposes */
252 isds_error isds_bogus_request(struct isds_ctx *context);
254 /*int isds_get_message(struct isds_ctx *context, const unsigned int id,
255 struct isds_message **message);
256 int isds_send_message(struct isds_ctx *context, struct isds_message *message);
257 int isds_list_messages(struct isds_ctx *context, struct isds_message **message);
258 int isds_find_recipient(struct isds_ctx *context, const struct address *pattern,
259 struct isds_address **address);
261 int isds_message_free(struct isds_message **message);
262 int isds_address_free(struct isds_address **address);
265 /* Deallocate structure isds_DbOwnerInfo recursively and NULL it */
266 void isds_DbOwnerInfo_free(struct isds_DbOwnerInfo **db_owner_info);
268 #endif