-/* $Id: api.h,v 1.28 2005-08-09 09:35:25 adam Exp $
+/* $Id: api.h,v 1.32 2006-03-31 15:58:03 adam Exp $
Copyright (C) 1995-2005
Index Data ApS
YAZ_BEGIN_CDECL
+/*
+ expand GCC_ATTRIBUTE if GCC is in use. See :
+ http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html
+*/
+
+#ifndef GCC_ATTRIBUTE
+#ifdef __GNUC__
+#define GCC_ATTRIBUTE(x) __attribute__ (x)
+#else
+#define GCC_ATTRIBUTE(x)
+#endif
+#endif
+
typedef struct {
int processed;
int inserted;
This function is a simplified version of zebra_start_res.
*/
YAZ_EXPORT
-ZebraService zebra_start(const char *configName);
+ZebraService zebra_start(const char *configName
+ ) GCC_ATTRIBUTE((warn_unused_result));
/** \fn ZebraService zebra_start_res(const char *configName, \
Res def_res, Res over_res)
*/
YAZ_EXPORT
ZebraService zebra_start_res(const char *configName,
- Res def_res, Res over_res);
+ Res def_res, Res over_res
+ ) GCC_ATTRIBUTE((warn_unused_result));
/**
\brief stops a Zebra service.
one handle is sufficient
*/
YAZ_EXPORT
-ZebraHandle zebra_open(ZebraService zs);
+ZebraHandle zebra_open(ZebraService zs, Res res
+ ) GCC_ATTRIBUTE((warn_unused_result));
/**
\brief Destroys Zebra session handle.
YAZ_EXPORT
void zebra_result(ZebraHandle zh, int *code, char **addinfo);
-/**
- \brief Clears last error.
- \param zh zebra session handle.
-*/
-YAZ_EXPORT
-void zebra_clearError(ZebraHandle zh);
-
-
/**
\brief Set limit before Zebra does approx hit count
\param zh session handle
int *statuses);
+/**
+ \brief returns number of term info terms assocaited with result set
+ \param zh session handle
+ \param setname result set name
+ \param num_terms number of terms returned in this integer
+ This function is used in conjunction with zebra_result_set_term_info.
+ If operation was successful, ZEBRA_OK is returned; otherwise
+ ZEBRA_FAIL is returned (typically non-existing setname)
+*/
YAZ_EXPORT
ZEBRA_RES zebra_result_set_term_no(ZebraHandle zh, const char *setname,
int *num_terms);
+/**
+ \brief returns information about a term assocated with a result set
+ \param zh session handle
+ \param setname result set name
+ \param no the term we want to know about (0=first, 1=second,..)
+ \param count the number of occurrences of this term, aka hits (output)
+ \param approx about hits: 0=exact,1=approx (output)
+ \param termbuf buffer for term string (intput, output)
+ \param termlen size of termbuf (input=max, output=actual length)
+ \param term_ref_id if non-NULL *term_ref_id holds term reference
+
+ Returns information about one search term associated with result set.
+ Use zebra_result_set_term_no to read total number of terms associated
+ with result set. If this function can not return information,
+ due to no out of range or bad result set name, ZEBRA_FAIL is
+ returned.
+ The passed termbuf must be able to hold at least *termlen characters.
+ Upon completion, *termlen holds actual length of search term.
+*/
YAZ_EXPORT
ZEBRA_RES zebra_result_set_term_info(ZebraHandle zh, const char *setname,
int no, zint *count, int *approx,
int action);
YAZ_EXPORT
-ZEBRA_RES zebra_begin_trans(ZebraHandle zh, int rw);
+ZEBRA_RES zebra_begin_trans(ZebraHandle zh, int rw
+ ) GCC_ATTRIBUTE((warn_unused_result));
YAZ_EXPORT
-ZEBRA_RES zebra_end_trans(ZebraHandle zh);
+ZEBRA_RES zebra_end_trans(ZebraHandle zh
+ ) GCC_ATTRIBUTE((warn_unused_result));
YAZ_EXPORT
ZEBRA_RES zebra_end_transaction(ZebraHandle zh,
int force_update);
YAZ_EXPORT
-int zebra_resultSetTerms(ZebraHandle zh, const char *setname,
- int no, zint *count,
- int *type, char *out, size_t *len);
-
-YAZ_EXPORT
ZEBRA_RES zebra_sort(ZebraHandle zh, ODR stream,
int num_input_setnames,
const char **input_setnames,
const char *output_setname,
Z_SortKeySpecList *sort_sequence,
- int *sort_status);
+ int *sort_status
+ ) GCC_ATTRIBUTE((warn_unused_result));
YAZ_EXPORT
ZEBRA_RES zebra_select_databases(ZebraHandle zh, int num_bases,
- const char **basenames);
+ const char **basenames
+ ) GCC_ATTRIBUTE((warn_unused_result));
YAZ_EXPORT
-ZEBRA_RES zebra_select_database(ZebraHandle zh, const char *basename);
+ZEBRA_RES zebra_select_database(ZebraHandle zh, const char *basename
+ ) GCC_ATTRIBUTE((warn_unused_result));
YAZ_EXPORT
void zebra_shadow_enable(ZebraHandle zh, int value);
* \section intro_sec Introduction
*
* Zebra is a search engine for structure data, such as XML, MARC
- * and others. The following chapters briefly describe each of
+ * and others.
+ *
+ * API users should read the api.h for all the public definitions.
+ *
+ * The remaining sections briefly describe each of
* Zebra major modules/components.
*
* \section util Base Utilities