Cleaning zebraapi (return conventions etc)
[idzebra-moved-to-github.git] / include / zebraapi.h
1 /* $Id: zebraapi.h,v 1.8 2003-06-20 14:21:23 heikki Exp $
2    Copyright (C) 1995,1996,1997,1998,1999,2000,2001,2002,2003
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 /* Return codes:
24  * Most functions return an int. Unix-like, 0 means OK, 
25  * non-zero means an error. The error info should be available
26  * via zebra_errCode and friends. 
27  */
28
29 #ifndef ZEBRAAPI_H
30 #define ZEBRAAPI_H
31
32 #include <yaz/odr.h>
33 #include <yaz/oid.h>
34 #include <yaz/proto.h>
35 #include <zebraver.h>
36
37 /* Fixme! Compare string (ignore case) */
38 #ifdef WIN32
39 #define STRCASECMP      stricmp
40 #else
41 #define STRCASECMP      strcasecmp
42 #endif
43
44 YAZ_BEGIN_CDECL
45
46 struct recordGroup {
47     char  *groupName;
48     char  *databaseName;
49     char  *path;
50     char  *recordId;
51     char  *recordType;
52     int   flagStoreData;
53     int   flagStoreKeys;
54     int   flagRw;
55     int   fileVerboseLimit;
56     int   databaseNamePath;
57     int   explainDatabase;
58     int   followLinks;
59 };
60
61 typedef struct {
62   int processed;
63   int inserted;
64   int updated;
65   int deleted;
66   long utime;
67   long stime;
68 } ZebraTransactionStatus;
69
70 /* Retrieval Record Descriptor */
71 typedef struct {
72     int errCode;         /* non-zero if error when fetching this */
73     char *errString;     /* error string */
74     int position;        /* position of record in result set (1,2,..) */
75     char *buf;           /* record buffer (void pointer really) */
76     int len;             /* length */
77     oid_value format;    /* record syntax */
78     char *base; 
79     int  sysno;
80     int  score;
81 } ZebraRetrievalRecord;
82
83 /* Scan Term Descriptor */
84 typedef struct {
85     int occurrences;     /* scan term occurrences */
86     char *term;          /* scan term string */
87 } ZebraScanEntry;
88
89 typedef struct zebra_session *ZebraHandle;
90 typedef struct zebra_service *ZebraService;
91
92
93 /******
94  * Starting and stopping 
95  */
96
97 /* Start Zebra using file 'configName' (usually zebra.cfg) */
98 /* There should be exactly one ZebraService */
99 YAZ_EXPORT ZebraService zebra_start (const char *configName);
100
101 /* Close the whole Zebra */
102 YAZ_EXPORT int zebra_stop (ZebraService zs);
103
104
105 /* Open a ZebraHandle */
106 /* There should be one handle for each thred doing something */
107 /* with zebra, be that searching or indexing. In simple apps */
108 /* one handle is sufficient */
109 YAZ_EXPORT ZebraHandle zebra_open (ZebraService zs);
110
111 /* Close handle */
112 YAZ_EXPORT int zebra_close (ZebraHandle zh);
113
114 /*********
115  * Error handling 
116  */
117
118 /* last error code */
119 YAZ_EXPORT int zebra_errCode (ZebraHandle zh);
120
121 /* string representatio of above */
122 YAZ_EXPORT const char *zebra_errString (ZebraHandle zh);
123
124 /* extra information associated with error */
125 YAZ_EXPORT char *zebra_errAdd (ZebraHandle zh);
126
127 /* get the result code and addinfo from zh */
128 YAZ_EXPORT int zebra_result (ZebraHandle zh, int *code, char **addinfo);
129 /* FIXME - why is this needed?? -H */
130
131 /* clear them error things */
132 YAZ_EXPORT void zebra_clearError(ZebraHandle zh);
133
134 /**************
135  * Searching 
136  */
137
138 /* Search using PQF Query */
139 YAZ_EXPORT int zebra_search_PQF (ZebraHandle zh, const char *pqf_query,
140                                  const char *setname, int *numhits);
141
142 /* Search using RPN Query */
143 YAZ_EXPORT int zebra_search_RPN (ZebraHandle zh, ODR o, Z_RPNQuery *query,
144                                   const char *setname, int *hits);
145
146 /* Retrieve record(s) */
147 YAZ_EXPORT int zebra_records_retrieve (ZebraHandle zh, ODR stream,
148                        const char *setname, Z_RecordComposition *comp,
149                        oid_value input_format,
150                        int num_recs, ZebraRetrievalRecord *recs);
151
152 /* Delete Result Set(s) */
153 YAZ_EXPORT int zebra_deleleResultSet(ZebraHandle zh, int function,
154                                      int num_setnames, char **setnames,
155                                      int *statuses);
156
157
158 /* Browse */
159 YAZ_EXPORT int zebra_scan (ZebraHandle zh, ODR stream,
160                             Z_AttributesPlusTerm *zapt,
161                             oid_value attributeset,
162                             int *position, int *num_entries,
163                             ZebraScanEntry **list,
164                             int *is_partial);
165
166    
167           
168 /*********
169  * Other 
170  */
171                       
172 /* do authentication */
173 YAZ_EXPORT int zebra_auth (ZebraHandle zh, const char *user, const char *pass);
174
175 /* Character normalisation on specific register .
176    This routine is subject to change - do not use. */
177 YAZ_EXPORT int zebra_string_norm (ZebraHandle zh, unsigned reg_id,
178                                   const char *input_str, int input_len,
179                                   char *output_str, int output_len);
180
181
182 /******
183  * Admin 
184  */                   
185           
186 YAZ_EXPORT int zebra_create_database (ZebraHandle zh, const char *db);
187
188
189 YAZ_EXPORT int zebra_admin_shutdown (ZebraHandle zh);
190 YAZ_EXPORT int zebra_admin_start (ZebraHandle zh);
191
192 YAZ_EXPORT int zebra_shutdown (ZebraService zs);
193
194 YAZ_EXPORT int zebra_admin_import_begin (ZebraHandle zh, const char *database,
195                                           const char *record_type);
196
197 YAZ_EXPORT int zebra_admin_import_segment (ZebraHandle zh,
198                                             Z_Segment *segment);
199
200 YAZ_EXPORT int zebra_admin_import_end (ZebraHandle zh);
201
202 int zebra_admin_exchange_record (ZebraHandle zh,
203                                  const char *database,
204                                  const char *rec_buf,
205                                  size_t rec_len,
206                                  const char *recid_buf, size_t recid_len,
207                                  int action);
208
209 int zebra_begin_trans (ZebraHandle zh, int rw);
210 int zebra_end_trans (ZebraHandle zh);
211 int zebra_end_transaction (ZebraHandle zh, ZebraTransactionStatus *stat);
212
213 int zebra_commit (ZebraHandle zh);
214 int zebra_clean (ZebraHandle zh);
215
216 int zebra_init (ZebraHandle zh);
217 int zebra_compact (ZebraHandle zh);
218 int zebra_repository_update (ZebraHandle zh);
219 int zebra_repository_delete (ZebraHandle zh);
220 int zebra_repository_show (ZebraHandle zh);
221 int zebra_record_insert (ZebraHandle zh, const char *buf, int len, int *sysno);
222
223 YAZ_EXPORT int zebra_set_group (ZebraHandle zh, struct recordGroup *rg);
224
225
226 YAZ_EXPORT int zebra_resultSetTerms (ZebraHandle zh, const char *setname, 
227                                      int no, int *count, 
228                                      int *type, char *out, size_t *len);
229
230 YAZ_EXPORT int zebra_sort (ZebraHandle zh, ODR stream,
231                             int num_input_setnames,
232                             const char **input_setnames,
233                             const char *output_setname,
234                             Z_SortKeySpecList *sort_sequence,
235                             int *sort_status);
236
237
238 YAZ_EXPORT
239 int zebra_select_databases (ZebraHandle zh, int num_bases, 
240                             const char **basenames);
241
242 YAZ_EXPORT
243 int zebra_select_database (ZebraHandle zh, const char *basename);
244
245 YAZ_EXPORT
246 int zebra_shadow_enable (ZebraHandle zh, int value);
247
248 YAZ_EXPORT
249 int zebra_register_statistics (ZebraHandle zh, int dumpdict);
250
251 YAZ_EXPORT
252 int zebra_record_encoding (ZebraHandle zh, const char *encoding);
253
254 /* Resources */
255 YAZ_EXPORT
256 int zebra_set_resource(ZebraHandle zh, const char *name, const char *value);
257 YAZ_EXPORT
258 const char *zebra_get_resource(ZebraHandle zh, 
259                 const char *name, const char *defaultvalue);
260
261
262 YAZ_END_CDECL                                 
263 #endif