1 /* $Id: api.h,v 1.9 2005-01-16 23:14:27 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
90 (const char *configName);
92 /** \fn ZebraService zebra_start_res(const char *configName,
93 Res def_res, Res over_res)
94 * \brief starts a Zebra service with resources.
95 * \param configName name of configuration file
96 * \param def_res default resources
97 * \param over_res overriding resources
99 * This function typically called once in a program. A Zebra Service
100 * acts as a factory for Zebra session handles.
103 ZebraService zebra_start_res(const char *configName,
104 Res def_res, Res over_res);
106 /** \fn int zebra_stop(ZebraService zs)
107 * \brief stops a Zebra service.
108 * \param zs service handle
110 * Frees resources used by the service.
113 int zebra_stop(ZebraService zs);
115 /** \fn void zebra_filter_info(ZebraService zs, void *cd,
116 void(*cb)(void *cd, const char *name))
117 * \brief lists enabled Zebra filters
118 * \param zs service handle
119 * \param cd callback parameter (opaque)
120 * \param cb callback function
123 void zebra_filter_info(ZebraService zs, void *cd,
124 void (*cb)(void *cd, const char *name));
127 /** \fn ZebraHandle zebra_open(ZebraService zs)
128 * \brief creates a Zebra session handle within service.
129 * \param zs service handle.
131 * There should be one handle for each thread doing something
132 * with zebra, be that searching or indexing. In simple apps
133 * one handle is sufficient
135 YAZ_EXPORT ZebraHandle zebra_open(ZebraService zs);
137 /** \fn int zebra_close(ZebraHandle zh)
138 * \brief destroys Zebra session handle.
139 * \param zh zebra session handle.
141 YAZ_EXPORT int zebra_close(ZebraHandle zh);
147 /** \fn int zebra_errCode(ZebraHandle zh)
148 * \brief returns error code for last error
149 * \param zh zebra session handle.
151 YAZ_EXPORT int zebra_errCode(ZebraHandle zh);
153 /** \fn const char *zebra_errString(ZebraHandle zh)
154 * \brief returns error string for last error
155 * \param zh zebra session handle.
157 YAZ_EXPORT const char *zebra_errString(ZebraHandle zh);
159 /** \fn char *zebra_errAdd(ZebraHandle zh)
160 * \brief returns additional info for last error
161 * \param zh zebra session handle.
163 YAZ_EXPORT char *zebra_errAdd(ZebraHandle zh);
165 /** \fn int zebra_result(ZebraHandle zh, int *code, char **addinfo)
166 * \brief returns error code and additional info for last error
167 * \param zh zebra session handle.
168 * \param code pointer to returned error code
169 * \param addinfo pointer to returned additional info
171 YAZ_EXPORT int zebra_result(ZebraHandle zh, int *code, char **addinfo);
173 /** \fn void zebra_clearError(ZebraHandle zh)
174 * \brief clears last error.
175 * \param zh zebra session handle.
177 YAZ_EXPORT void zebra_clearError(ZebraHandle zh);
183 /* Search using PQF Query */
184 YAZ_EXPORT int zebra_search_PQF(ZebraHandle zh, const char *pqf_query,
185 const char *setname, int *numhits);
187 /* Search using RPN Query */
188 YAZ_EXPORT int zebra_search_RPN(ZebraHandle zh, ODR o, Z_RPNQuery *query,
189 const char *setname, int *hits);
191 /* Retrieve record(s) */
192 YAZ_EXPORT int zebra_records_retrieve(ZebraHandle zh, ODR stream,
193 const char *setname, Z_RecordComposition *comp,
194 oid_value input_format,
195 int num_recs, ZebraRetrievalRecord *recs);
197 /* Delete Result Set(s) */
198 YAZ_EXPORT int zebra_deleleResultSet(ZebraHandle zh, int function,
199 int num_setnames, char **setnames,
204 YAZ_EXPORT int zebra_scan(ZebraHandle zh, ODR stream,
205 Z_AttributesPlusTerm *zapt,
206 oid_value attributeset,
207 int *position, int *num_entries,
208 ZebraScanEntry **list,
217 /* do authentication */
218 YAZ_EXPORT int zebra_auth(ZebraHandle zh, const char *user, const char *pass);
220 /* Character normalisation on specific register .
221 This routine is subject to change - do not use. */
222 YAZ_EXPORT int zebra_string_norm(ZebraHandle zh, unsigned reg_id,
223 const char *input_str, int input_len,
224 char *output_str, int output_len);
231 YAZ_EXPORT int zebra_create_database(ZebraHandle zh, const char *db);
232 YAZ_EXPORT int zebra_drop_database(ZebraHandle zh, const char *db);
234 YAZ_EXPORT int zebra_admin_shutdown(ZebraHandle zh);
235 YAZ_EXPORT int zebra_admin_start(ZebraHandle zh);
237 YAZ_EXPORT int zebra_shutdown(ZebraService zs);
239 YAZ_EXPORT int zebra_admin_import_begin(ZebraHandle zh, const char *database,
240 const char *record_type);
242 YAZ_EXPORT int zebra_admin_import_segment(ZebraHandle zh,
245 YAZ_EXPORT int zebra_admin_import_end(ZebraHandle zh);
247 int zebra_admin_exchange_record(ZebraHandle zh,
250 const char *recid_buf, size_t recid_len,
253 int zebra_begin_trans(ZebraHandle zh, int rw);
254 int zebra_end_trans(ZebraHandle zh);
255 int zebra_end_transaction(ZebraHandle zh, ZebraTransactionStatus *stat);
257 int zebra_commit(ZebraHandle zh);
258 int zebra_clean(ZebraHandle zh);
260 int zebra_init(ZebraHandle zh);
261 int zebra_compact(ZebraHandle zh);
262 int zebra_repository_update(ZebraHandle zh, const char *path);
263 int zebra_repository_delete(ZebraHandle zh, const char *path);
264 int zebra_repository_show(ZebraHandle zh, const char *path);
266 int zebra_add_record(ZebraHandle zh, const char *buf, int buf_size);
268 int zebra_insert_record(ZebraHandle zh,
269 const char *recordType,
270 SYSNO *sysno, const char *match, const char *fname,
271 const char *buf, int buf_size,
273 int zebra_update_record(ZebraHandle zh,
274 const char *recordType,
275 SYSNO *sysno, const char *match, const char *fname,
276 const char *buf, int buf_size,
278 int zebra_delete_record(ZebraHandle zh,
279 const char *recordType,
280 SYSNO *sysno, const char *match, const char *fname,
281 const char *buf, int buf_size,
284 YAZ_EXPORT int zebra_resultSetTerms(ZebraHandle zh, const char *setname,
286 int *type, char *out, size_t *len);
288 YAZ_EXPORT int zebra_sort(ZebraHandle zh, ODR stream,
289 int num_input_setnames,
290 const char **input_setnames,
291 const char *output_setname,
292 Z_SortKeySpecList *sort_sequence,
296 int zebra_select_databases(ZebraHandle zh, int num_bases,
297 const char **basenames);
300 int zebra_select_database(ZebraHandle zh, const char *basename);
303 int zebra_shadow_enable(ZebraHandle zh, int value);
306 int zebra_register_statistics(ZebraHandle zh, int dumpdict);
309 int zebra_record_encoding(ZebraHandle zh, const char *encoding);
312 int zebra_record_encoding(ZebraHandle zh, const char *encoding);
315 int zebra_octet_term_encoding(ZebraHandle zh, const char *encoding);
319 int zebra_set_resource(ZebraHandle zh, const char *name, const char *value);
321 const char *zebra_get_resource(ZebraHandle zh,
322 const char *name, const char *defaultvalue);
325 YAZ_EXPORT void zebra_pidfname(ZebraService zs, char *path);
335 ZebraMetaRecord *zebra_meta_records_create(ZebraHandle zh,
337 int num, zint *positions);
341 ZebraMetaRecord *zebra_meta_records_create_range(ZebraHandle zh,
343 zint start, int num);
346 void zebra_meta_records_destroy(ZebraHandle zh, ZebraMetaRecord *records,