1 /* $Id: api.h,v 1.10 2005-01-21 13:19:25 adam Exp $
2 Copyright (C) 1995-2005
5 This file is part of the Zebra server.
7 Zebra is free software; you can redistribute it and/or modify it under
8 the terms of the GNU General Public License as published by the Free
9 Software Foundation; either version 2, or (at your option) any later
12 Zebra is distributed in the hope that it will be useful, but WITHOUT ANY
13 WARRANTY; without even the implied warranty of MERCHANTABILITY or
14 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
17 You should have received a copy of the GNU General Public License
18 along with Zebra; see the file LICENSE.zebra. If not, write to the
19 Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
29 * Most functions return an int. Unix-like, 0 means OK,
30 * non-zero means an error. The error info should be available
31 * via zebra_errCode and friends.
39 #include <yaz/proto.h>
40 #include <idzebra/res.h>
41 #include <idzebra/version.h>
52 } ZebraTransactionStatus;
54 /* Retrieval Record Descriptor */
56 int errCode; /* non-zero if error when fetching this */
57 char *errString; /* error string */
58 int position; /* position of record in result set (1,2,..) */
59 char *buf; /* record buffer (void pointer really) */
61 oid_value format; /* record syntax */
65 } ZebraRetrievalRecord;
67 /* Scan Term Descriptor */
69 int occurrences; /* scan term occurrences */
70 char *term; /* scan term string */
74 * \brief a Zebra Handle - (session)
76 typedef struct zebra_session *ZebraHandle;
79 * \brief a Zebra Service handle
81 typedef struct zebra_service *ZebraService;
83 /** \fn ZebraService zebra_start(const char *configName)
84 * \brief starts a Zebra service.
85 * \param configName name of configuration file
87 * This function is a simplified version of zebra_start_res.
89 YAZ_EXPORT ZebraService zebra_start(const char *configName);
91 /** \fn ZebraService zebra_start_res(const char *configName,
92 Res def_res, Res over_res)
93 * \brief starts a Zebra service with resources.
94 * \param configName name of configuration file
95 * \param def_res default resources
96 * \param over_res overriding resources
98 * This function typically called once in a program. A Zebra Service
99 * acts as a factory for Zebra session handles.
102 ZebraService zebra_start_res(const char *configName,
103 Res def_res, Res over_res);
105 /** \fn int zebra_stop(ZebraService zs)
106 * \brief stops a Zebra service.
107 * \param zs service handle
109 * Frees resources used by the service.
112 int zebra_stop(ZebraService zs);
114 /** \fn void zebra_filter_info(ZebraService zs, void *cd,
115 void(*cb)(void *cd, const char *name))
116 * \brief lists enabled Zebra filters
117 * \param zs service handle
118 * \param cd callback parameter (opaque)
119 * \param cb callback function
122 void zebra_filter_info(ZebraService zs, void *cd,
123 void (*cb)(void *cd, const char *name));
126 /** \fn ZebraHandle zebra_open(ZebraService zs)
127 * \brief creates a Zebra session handle within service.
128 * \param zs service handle.
130 * There should be one handle for each thread doing something
131 * with zebra, be that searching or indexing. In simple apps
132 * one handle is sufficient
134 YAZ_EXPORT ZebraHandle zebra_open(ZebraService zs);
136 /** \fn int zebra_close(ZebraHandle zh)
137 * \brief destroys Zebra session handle.
138 * \param zh zebra session handle.
140 YAZ_EXPORT int zebra_close(ZebraHandle zh);
146 /** \fn int zebra_errCode(ZebraHandle zh)
147 * \brief returns error code for last error
148 * \param zh zebra session handle.
150 YAZ_EXPORT int zebra_errCode(ZebraHandle zh);
152 /** \fn const char *zebra_errString(ZebraHandle zh)
153 * \brief returns error string for last error
154 * \param zh zebra session handle.
156 YAZ_EXPORT const char *zebra_errString(ZebraHandle zh);
158 /** \fn char *zebra_errAdd(ZebraHandle zh)
159 * \brief returns additional info for last error
160 * \param zh zebra session handle.
162 YAZ_EXPORT char *zebra_errAdd(ZebraHandle zh);
164 /** \fn int zebra_result(ZebraHandle zh, int *code, char **addinfo)
165 * \brief returns error code and additional info for last error
166 * \param zh zebra session handle.
167 * \param code pointer to returned error code
168 * \param addinfo pointer to returned additional info
170 YAZ_EXPORT int zebra_result(ZebraHandle zh, int *code, char **addinfo);
172 /** \fn void zebra_clearError(ZebraHandle zh)
173 * \brief clears last error.
174 * \param zh zebra session handle.
176 YAZ_EXPORT void zebra_clearError(ZebraHandle zh);
178 /** \fn int zebra_search_PQF(ZebraHandle zh, const char *pqf_query,
179 const char *setname, int *numhits)
180 * \brief Search using PQF Query
181 * \param zh session handle
182 * \param pqf_query query
183 * \param setname name of resultset
184 * \param number of hits is returned
186 YAZ_EXPORT int zebra_search_PQF(ZebraHandle zh, const char *pqf_query,
187 const char *setname, int *numhits);
189 /** \fn int zebra_search_RPN(ZebraHandle zh, Z_RPNQuery *query,
190 const char *setname, int *numhits)
191 * \brief Search using RPN Query
192 * \param zh session handle
193 * \param query RPN query using YAZ structure
194 * \param setname name of resultset
195 * \param number of hits is returned
197 YAZ_EXPORT int zebra_search_RPN(ZebraHandle zh, ODR o, Z_RPNQuery *query,
198 const char *setname, int *hits);
201 int zebra_records_retrieve(ZebraHandle zh, ODR stream, const char *setname, Z_RecordComposition *comp, oid_value input_format, int num_recs, ZebraRetrievalRecord *recs)
202 \brief retrieve records from result set (after search)
203 * \param zh session handle
204 * \param stream allocate records returned using this ODR
205 * \param setname name of result set to retrieve records from
206 * \param comp Z39.50 record composition
207 * \param input_format transfer syntax (OID)
208 * \param num_recs number of records to retrieve
209 * \param recs store records in this structure (size is num_recs)
211 YAZ_EXPORT int zebra_records_retrieve(ZebraHandle zh, ODR stream,
212 const char *setname, Z_RecordComposition *comp,
213 oid_value input_format,
214 int num_recs, ZebraRetrievalRecord *recs);
216 YAZ_EXPORT int zebra_deleleResultSet(ZebraHandle zh, int function,
217 int num_setnames, char **setnames,
222 YAZ_EXPORT int zebra_scan(ZebraHandle zh, ODR stream,
223 Z_AttributesPlusTerm *zapt,
224 oid_value attributeset,
225 int *position, int *num_entries,
226 ZebraScanEntry **list,
235 /* do authentication */
236 YAZ_EXPORT int zebra_auth(ZebraHandle zh, const char *user, const char *pass);
238 /* Character normalisation on specific register .
239 This routine is subject to change - do not use. */
240 YAZ_EXPORT int zebra_string_norm(ZebraHandle zh, unsigned reg_id,
241 const char *input_str, int input_len,
242 char *output_str, int output_len);
249 YAZ_EXPORT int zebra_create_database(ZebraHandle zh, const char *db);
250 YAZ_EXPORT int zebra_drop_database(ZebraHandle zh, const char *db);
252 YAZ_EXPORT int zebra_admin_shutdown(ZebraHandle zh);
253 YAZ_EXPORT int zebra_admin_start(ZebraHandle zh);
255 YAZ_EXPORT int zebra_shutdown(ZebraService zs);
257 YAZ_EXPORT int zebra_admin_import_begin(ZebraHandle zh, const char *database,
258 const char *record_type);
260 YAZ_EXPORT int zebra_admin_import_segment(ZebraHandle zh,
263 YAZ_EXPORT int zebra_admin_import_end(ZebraHandle zh);
265 int zebra_admin_exchange_record(ZebraHandle zh,
268 const char *recid_buf, size_t recid_len,
271 int zebra_begin_trans(ZebraHandle zh, int rw);
272 int zebra_end_trans(ZebraHandle zh);
273 int zebra_end_transaction(ZebraHandle zh, ZebraTransactionStatus *stat);
275 int zebra_commit(ZebraHandle zh);
276 int zebra_clean(ZebraHandle zh);
278 int zebra_init(ZebraHandle zh);
279 int zebra_compact(ZebraHandle zh);
280 int zebra_repository_update(ZebraHandle zh, const char *path);
281 int zebra_repository_delete(ZebraHandle zh, const char *path);
282 int zebra_repository_show(ZebraHandle zh, const char *path);
284 int zebra_add_record(ZebraHandle zh, const char *buf, int buf_size);
286 int zebra_insert_record(ZebraHandle zh,
287 const char *recordType,
288 SYSNO *sysno, const char *match, const char *fname,
289 const char *buf, int buf_size,
291 int zebra_update_record(ZebraHandle zh,
292 const char *recordType,
293 SYSNO *sysno, const char *match, const char *fname,
294 const char *buf, int buf_size,
296 int zebra_delete_record(ZebraHandle zh,
297 const char *recordType,
298 SYSNO *sysno, const char *match, const char *fname,
299 const char *buf, int buf_size,
302 YAZ_EXPORT int zebra_resultSetTerms(ZebraHandle zh, const char *setname,
304 int *type, char *out, size_t *len);
306 YAZ_EXPORT int zebra_sort(ZebraHandle zh, ODR stream,
307 int num_input_setnames,
308 const char **input_setnames,
309 const char *output_setname,
310 Z_SortKeySpecList *sort_sequence,
314 int zebra_select_databases(ZebraHandle zh, int num_bases,
315 const char **basenames);
318 int zebra_select_database(ZebraHandle zh, const char *basename);
321 int zebra_shadow_enable(ZebraHandle zh, int value);
324 int zebra_register_statistics(ZebraHandle zh, int dumpdict);
327 int zebra_record_encoding(ZebraHandle zh, const char *encoding);
330 int zebra_record_encoding(ZebraHandle zh, const char *encoding);
333 int zebra_octet_term_encoding(ZebraHandle zh, const char *encoding);
337 int zebra_set_resource(ZebraHandle zh, const char *name, const char *value);
339 const char *zebra_get_resource(ZebraHandle zh,
340 const char *name, const char *defaultvalue);
343 YAZ_EXPORT void zebra_pidfname(ZebraService zs, char *path);
353 ZebraMetaRecord *zebra_meta_records_create(ZebraHandle zh,
355 int num, zint *positions);
359 ZebraMetaRecord *zebra_meta_records_create_range(ZebraHandle zh,
361 zint start, int num);
364 void zebra_meta_records_destroy(ZebraHandle zh, ZebraMetaRecord *records,