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 */
10 IE_SUCCESS
= 0, /* No error, just for C conveniece (0 means Ok) */
11 IE_ERROR
, /* unsepcified error */
49 /* Return text description of ISDS error */
50 char *isds_strerror(const isds_error error
);
68 /* Box status from point of view of accesibilty */
70 DBSTATE_ACCESIBLE
= 1,
71 DBSTATE_TEMP_UNACCESSIBLE
= 2,
72 DBSTATE_NOT_YET_ACCESSIBLE
= 3,
73 DBSTATE_PERM_UNACCESSIBLE
= 4,
78 struct isds_PersonName
{
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
91 char *biCounty
; /* German: Bezirk, Czech: okres */
99 char *adNumberInStreet
;
100 char *adNumberInMunicipality
;
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 */
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 */
118 char *identifier
; /* External box identifier for data
119 provider (OVM, PO, maybe PFO)
121 char *registryCode
; /* PFO External registry code
123 long int *dbState
; /* Box state; 1 <=> active box;
124 long int beacause xsd:integer
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 */
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;
149 struct isds_message {
150 struct isds_message *next;
151 struct isds_address *sender;
152 struct isds_address *recipient;
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
);
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.
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.
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.
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
);