include/idzebra/api.h

   1 /* $Id: api.h,v 1.11 2005-01-21 18:41:19 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(const char *configName);
  90
  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
  97  *
  98  * This function typically called once in a program. A Zebra Service
  99  * acts as a factory for Zebra session handles.
 100  */
 101 YAZ_EXPORT
 102 ZebraService zebra_start_res(const char *configName,
 103                          Res def_res, Res over_res);
 104
 105 /** \fn int zebra_stop(ZebraService zs)
 106  * \brief stops a Zebra service.
 107  * \param zs service handle
 108  *
 109  * Frees resources used by the service.
 110  */
 111 YAZ_EXPORT
 112 int zebra_stop(ZebraService zs);
 113
 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
 120  */
 121 YAZ_EXPORT
 122 void zebra_filter_info(ZebraService zs, void *cd,
 123                   void (*cb)(void *cd, const char *name));
 124
 125
 126 /** \fn ZebraHandle zebra_open(ZebraService zs)
 127  * \brief creates a Zebra session handle within service.
 128  * \param zs service handle.
 129  *
 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
 133  */
 134 YAZ_EXPORT ZebraHandle zebra_open(ZebraService zs);
 135
 136 /** \fn int zebra_close(ZebraHandle zh)
 137  * \brief destroys Zebra session handle.
 138  * \param zh zebra session handle.
 139  */
 140 YAZ_EXPORT int zebra_close(ZebraHandle zh);
 141
 142 /*********
 143  * Error handling
 144  */
 145
 146 /** \fn int zebra_errCode(ZebraHandle zh)
 147  * \brief returns error code for last error
 148  * \param zh zebra session handle.
 149  */
 150 YAZ_EXPORT int zebra_errCode(ZebraHandle zh);
 151
 152 /** \fn const char *zebra_errString(ZebraHandle zh)
 153  * \brief returns error string for last error
 154  * \param zh zebra session handle.
 155  */
 156 YAZ_EXPORT const char *zebra_errString(ZebraHandle zh);
 157
 158 /** \fn char *zebra_errAdd(ZebraHandle zh)
 159  * \brief returns additional info for last error
 160  * \param zh zebra session handle.
 161  */
 162 YAZ_EXPORT char *zebra_errAdd(ZebraHandle zh);
 163
 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
 169  */
 170 YAZ_EXPORT int zebra_result(ZebraHandle zh, int *code, char **addinfo);
 171
 172 /** \fn void zebra_clearError(ZebraHandle zh)
 173  * \brief clears last error.
 174  * \param zh zebra session handle.
 175  */
 176 YAZ_EXPORT void zebra_clearError(ZebraHandle zh);
 177
 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
 185  */
 186 YAZ_EXPORT int zebra_search_PQF(ZebraHandle zh, const char *pqf_query,
 187                                 const char *setname, int *numhits);
 188
 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
 196  */
 197 YAZ_EXPORT int zebra_search_RPN(ZebraHandle zh, ODR o, Z_RPNQuery *query,
 198                                 const char *setname, int *hits);
 199
 200 /** \fn
 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)
 210  */
 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);
 215
 216 YAZ_EXPORT int zebra_deleteResultSet(ZebraHandle zh, int function,
 217                                      int num_setnames, char **setnames,
 218                                      int *statuses);
 219
 220
 221 /* Browse */
 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,
 227                            int *is_partial);
 228
 229
 230
 231 /*********
 232  * Other
 233  */
 234
 235 /* do authentication */
 236 YAZ_EXPORT int zebra_auth(ZebraHandle zh, const char *user, const char *pass);
 237
 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);
 243
 244
 245 /******
 246  * Admin
 247  */
 248
 249 YAZ_EXPORT int zebra_create_database(ZebraHandle zh, const char *db);
 250 YAZ_EXPORT int zebra_drop_database(ZebraHandle zh, const char *db);
 251
 252 YAZ_EXPORT int zebra_admin_shutdown(ZebraHandle zh);
 253 YAZ_EXPORT int zebra_admin_start(ZebraHandle zh);
 254
 255 YAZ_EXPORT int zebra_shutdown(ZebraService zs);
 256
 257 YAZ_EXPORT int zebra_admin_import_begin(ZebraHandle zh, const char *database,
 258                                           const char *record_type);
 259
 260 YAZ_EXPORT int zebra_admin_import_segment(ZebraHandle zh,
 261                                             Z_Segment *segment);
 262
 263 YAZ_EXPORT int zebra_admin_import_end(ZebraHandle zh);
 264
 265 int zebra_admin_exchange_record(ZebraHandle zh,
 266                                  const char *rec_buf,
 267                                  size_t rec_len,
 268                                  const char *recid_buf, size_t recid_len,
 269                                  int action);
 270
 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);
 274
 275 int zebra_commit(ZebraHandle zh);
 276 int zebra_clean(ZebraHandle zh);
 277
 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);
 283
 284 int zebra_add_record(ZebraHandle zh, const char *buf, int buf_size);
 285
 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,
 290                          int force_update);
 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,
 295                          int force_update);
 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,
 300                          int force_update);
 301
 302 YAZ_EXPORT int zebra_resultSetTerms(ZebraHandle zh, const char *setname,
 303                                      int no, zint *count,
 304                                      int *type, char *out, size_t *len);
 305
 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,
 311                            int *sort_status);
 312
 313 YAZ_EXPORT
 314 int zebra_select_databases(ZebraHandle zh, int num_bases,
 315                             const char **basenames);
 316
 317 YAZ_EXPORT
 318 int zebra_select_database(ZebraHandle zh, const char *basename);
 319
 320 YAZ_EXPORT
 321 int zebra_shadow_enable(ZebraHandle zh, int value);
 322
 323 YAZ_EXPORT
 324 int zebra_register_statistics(ZebraHandle zh, int dumpdict);
 325
 326 YAZ_EXPORT
 327 int zebra_record_encoding(ZebraHandle zh, const char *encoding);
 328
 329 YAZ_EXPORT
 330 int zebra_record_encoding(ZebraHandle zh, const char *encoding);
 331
 332 YAZ_EXPORT
 333 int zebra_octet_term_encoding(ZebraHandle zh, const char *encoding);
 334
 335 /* Resources */
 336 YAZ_EXPORT
 337 int zebra_set_resource(ZebraHandle zh, const char *name, const char *value);
 338 YAZ_EXPORT
 339 const char *zebra_get_resource(ZebraHandle zh,
 340                 const char *name, const char *defaultvalue);
 341
 342
 343 YAZ_EXPORT void zebra_pidfname(ZebraService zs, char *path);
 344
 345 typedef struct {
 346     char *term;
 347     char *db;
 348     zint sysno;
 349     int score;
 350 } ZebraMetaRecord;
 351
 352 YAZ_EXPORT
 353 ZebraMetaRecord *zebra_meta_records_create(ZebraHandle zh,
 354                                            const char *name,
 355                                            int num, zint *positions);
 356
 357
 358 YAZ_EXPORT
 359 ZebraMetaRecord *zebra_meta_records_create_range(ZebraHandle zh,
 360                                                  const char *name,
 361                                                  zint start, int num);
 362
 363 YAZ_EXPORT
 364 void zebra_meta_records_destroy(ZebraHandle zh, ZebraMetaRecord *records,
 365                                 int num);
 366 YAZ_END_CDECL
 367 #endif