include/idzebra/api.h

   1 /* $Id: api.h,v 1.9 2005-01-16 23:14:27 adam Exp $
   2    Copyright (C) 1995-2005
   3    Index Data ApS
   4
   5 This file is part of the Zebra server.
   6
   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
  10 version.
  11
  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
  15 for more details.
  16
  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
  20 02111-1307, USA.
  21 */
  22
  23 /**
  24  * \file api.h
  25  * \brief Zebra API
  26  */
  27
  28 /* Return codes:
  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.
  32  */
  33
  34 #ifndef ZEBRAAPI_H
  35 #define ZEBRAAPI_H
  36
  37 #include <yaz/odr.h>
  38 #include <yaz/oid.h>
  39 #include <yaz/proto.h>
  40 #include <idzebra/res.h>
  41 #include <idzebra/version.h>
  42
  43 YAZ_BEGIN_CDECL
  44
  45 typedef struct {
  46   int processed;
  47   int inserted;
  48   int updated;
  49   int deleted;
  50   long utime;
  51   long stime;
  52 } ZebraTransactionStatus;
  53
  54 /* Retrieval Record Descriptor */
  55 typedef struct {
  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) */
  60     int len;             /* length */
  61     oid_value format;    /* record syntax */
  62     char *base;
  63     SYSNO sysno;
  64     int  score;
  65 } ZebraRetrievalRecord;
  66
  67 /* Scan Term Descriptor */
  68 typedef struct {
  69     int occurrences;     /* scan term occurrences */
  70     char *term;          /* scan term string */
  71 } ZebraScanEntry;
  72
  73 /** \var ZebraHandle
  74  * \brief a Zebra Handle - (session)
  75  */
  76 typedef struct zebra_session *ZebraHandle;
  77
  78 /** \var ZebraService
  79  * \brief a Zebra Service handle
  80  */
  81 typedef struct zebra_service *ZebraService;
  82
  83 /** \fn ZebraService zebra_start(const char *configName)
  84  * \brief starts a Zebra service.
  85  * \param configName name of configuration file
  86  *
  87  * This function is a simplified version of zebra_start_res.
  88  */
  89 YAZ_EXPORT ZebraService zebra_start
  90 (const char *configName);
  91
  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
  98  *
  99  * This function typically called once in a program. A Zebra Service
 100  * acts as a factory for Zebra session handles.
 101  */
 102 YAZ_EXPORT
 103 ZebraService zebra_start_res(const char *configName,
 104                          Res def_res, Res over_res);
 105
 106 /** \fn int zebra_stop(ZebraService zs)
 107  * \brief stops a Zebra service.
 108  * \param zs service handle
 109  *
 110  * Frees resources used by the service.
 111  */
 112 YAZ_EXPORT
 113 int zebra_stop(ZebraService zs);
 114
 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
 121  */
 122 YAZ_EXPORT
 123 void zebra_filter_info(ZebraService zs, void *cd,
 124                   void (*cb)(void *cd, const char *name));
 125
 126
 127 /** \fn ZebraHandle zebra_open(ZebraService zs)
 128  * \brief creates a Zebra session handle within service.
 129  * \param zs service handle.
 130  *
 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
 134  */
 135 YAZ_EXPORT ZebraHandle zebra_open(ZebraService zs);
 136
 137 /** \fn int zebra_close(ZebraHandle zh)
 138  * \brief destroys Zebra session handle.
 139  * \param zh zebra session handle.
 140  */
 141 YAZ_EXPORT int zebra_close(ZebraHandle zh);
 142
 143 /*********
 144  * Error handling
 145  */
 146
 147 /** \fn int zebra_errCode(ZebraHandle zh)
 148  * \brief returns error code for last error
 149  * \param zh zebra session handle.
 150  */
 151 YAZ_EXPORT int zebra_errCode(ZebraHandle zh);
 152
 153 /** \fn const char *zebra_errString(ZebraHandle zh)
 154  * \brief returns error string for last error
 155  * \param zh zebra session handle.
 156  */
 157 YAZ_EXPORT const char *zebra_errString(ZebraHandle zh);
 158
 159 /** \fn char *zebra_errAdd(ZebraHandle zh)
 160  * \brief returns additional info for last error
 161  * \param zh zebra session handle.
 162  */
 163 YAZ_EXPORT char *zebra_errAdd(ZebraHandle zh);
 164
 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
 170  */
 171 YAZ_EXPORT int zebra_result(ZebraHandle zh, int *code, char **addinfo);
 172
 173 /** \fn void zebra_clearError(ZebraHandle zh)
 174  * \brief clears last error.
 175  * \param zh zebra session handle.
 176  */
 177 YAZ_EXPORT void zebra_clearError(ZebraHandle zh);
 178
 179 /**************
 180  * Searching
 181  */
 182
 183 /* Search using PQF Query */
 184 YAZ_EXPORT int zebra_search_PQF(ZebraHandle zh, const char *pqf_query,
 185                                  const char *setname, int *numhits);
 186
 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);
 190
 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);
 196
 197 /* Delete Result Set(s) */
 198 YAZ_EXPORT int zebra_deleleResultSet(ZebraHandle zh, int function,
 199                                      int num_setnames, char **setnames,
 200                                      int *statuses);
 201
 202
 203 /* Browse */
 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,
 209                            int *is_partial);
 210
 211
 212
 213 /*********
 214  * Other
 215  */
 216
 217 /* do authentication */
 218 YAZ_EXPORT int zebra_auth(ZebraHandle zh, const char *user, const char *pass);
 219
 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);
 225
 226
 227 /******
 228  * Admin
 229  */
 230
 231 YAZ_EXPORT int zebra_create_database(ZebraHandle zh, const char *db);
 232 YAZ_EXPORT int zebra_drop_database(ZebraHandle zh, const char *db);
 233
 234 YAZ_EXPORT int zebra_admin_shutdown(ZebraHandle zh);
 235 YAZ_EXPORT int zebra_admin_start(ZebraHandle zh);
 236
 237 YAZ_EXPORT int zebra_shutdown(ZebraService zs);
 238
 239 YAZ_EXPORT int zebra_admin_import_begin(ZebraHandle zh, const char *database,
 240                                           const char *record_type);
 241
 242 YAZ_EXPORT int zebra_admin_import_segment(ZebraHandle zh,
 243                                             Z_Segment *segment);
 244
 245 YAZ_EXPORT int zebra_admin_import_end(ZebraHandle zh);
 246
 247 int zebra_admin_exchange_record(ZebraHandle zh,
 248                                  const char *rec_buf,
 249                                  size_t rec_len,
 250                                  const char *recid_buf, size_t recid_len,
 251                                  int action);
 252
 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);
 256
 257 int zebra_commit(ZebraHandle zh);
 258 int zebra_clean(ZebraHandle zh);
 259
 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);
 265
 266 int zebra_add_record(ZebraHandle zh, const char *buf, int buf_size);
 267
 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,
 272                          int force_update);
 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,
 277                          int force_update);
 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,
 282                          int force_update);
 283
 284 YAZ_EXPORT int zebra_resultSetTerms(ZebraHandle zh, const char *setname,
 285                                      int no, zint *count,
 286                                      int *type, char *out, size_t *len);
 287
 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,
 293                            int *sort_status);
 294
 295 YAZ_EXPORT
 296 int zebra_select_databases(ZebraHandle zh, int num_bases,
 297                             const char **basenames);
 298
 299 YAZ_EXPORT
 300 int zebra_select_database(ZebraHandle zh, const char *basename);
 301
 302 YAZ_EXPORT
 303 int zebra_shadow_enable(ZebraHandle zh, int value);
 304
 305 YAZ_EXPORT
 306 int zebra_register_statistics(ZebraHandle zh, int dumpdict);
 307
 308 YAZ_EXPORT
 309 int zebra_record_encoding(ZebraHandle zh, const char *encoding);
 310
 311 YAZ_EXPORT
 312 int zebra_record_encoding(ZebraHandle zh, const char *encoding);
 313
 314 YAZ_EXPORT
 315 int zebra_octet_term_encoding(ZebraHandle zh, const char *encoding);
 316
 317 /* Resources */
 318 YAZ_EXPORT
 319 int zebra_set_resource(ZebraHandle zh, const char *name, const char *value);
 320 YAZ_EXPORT
 321 const char *zebra_get_resource(ZebraHandle zh,
 322                 const char *name, const char *defaultvalue);
 323
 324
 325 YAZ_EXPORT void zebra_pidfname(ZebraService zs, char *path);
 326
 327 typedef struct {
 328     char *term;
 329     char *db;
 330     zint sysno;
 331     int score;
 332 } ZebraMetaRecord;
 333
 334 YAZ_EXPORT
 335 ZebraMetaRecord *zebra_meta_records_create(ZebraHandle zh,
 336                                            const char *name,
 337                                            int num, zint *positions);
 338
 339
 340 YAZ_EXPORT
 341 ZebraMetaRecord *zebra_meta_records_create_range(ZebraHandle zh,
 342                                                  const char *name,
 343                                                  zint start, int num);
 344
 345 YAZ_EXPORT
 346 void zebra_meta_records_destroy(ZebraHandle zh, ZebraMetaRecord *records,
 347                                 int num);
 348 YAZ_END_CDECL
 349 #endif