X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=include%2Fidzebra%2Fapi.h;h=cf6c387ea7f4f1478b6e8959c771a4651fc9bd29;hb=f2f159d942dae64203f266941c76bc487e33714e;hp=9cbb6fa5992a1e1143351f9dede045f5a3fa5c98;hpb=89895e559c05c44e538a732b1e072e28413ddc1f;p=idzebra-moved-to-github.git

diff --git a/include/idzebra/api.h b/include/idzebra/api.h
index 9cbb6fa..cf6c387 100644
--- a/include/idzebra/api.h
+++ b/include/idzebra/api.h
@@ -1,4 +1,4 @@
-/* $Id: api.h,v 1.23 2005-05-09 10:16:12 adam Exp $
+/* $Id: api.h,v 1.29 2005-08-09 10:01:03 adam Exp $
    Copyright (C) 1995-2005
    Index Data ApS
 
@@ -100,89 +100,98 @@ YAZ_EXPORT
 ZebraService zebra_start_res(const char *configName,
 			     Res def_res, Res over_res);
 
-/** \fn ZEBRA_RES zebra_stop(ZebraService zs)
-    \brief stops a Zebra service.
-    \param zs service handle
-    
-    Frees resources used by the service.
+/**
+   \brief stops a Zebra service.
+   \param zs service handle
+   
+   Frees resources used by the service.
 */
 YAZ_EXPORT
 ZEBRA_RES zebra_stop(ZebraService zs);
 
-/** \fn void zebra_filter_info(ZebraService zs, void *cd, \
-                               void(*cb)(void *cd, const char *name))
-    \brief lists enabled Zebra filters
-    \param zs service handle
-    \param cd callback parameter (opaque)
-    \param cb callback function
+/**
+   \brief Lists enabled Zebra filters
+   \param zs service handle
+   \param cd callback parameter (opaque)
+   \param cb callback function
  */
 YAZ_EXPORT
 void zebra_filter_info(ZebraService zs, void *cd,
 		       void (*cb)(void *cd, const char *name));
 
 
-/** \fn ZebraHandle zebra_open(ZebraService zs)
-    \brief creates a Zebra session handle within service.
-    \param zs service handle.
-    
-    There should be one handle for each thread doing something
-    with zebra, be that searching or indexing. In simple apps 
-    one handle is sufficient 
+/**
+   \brief Creates a Zebra session handle within service.
+   \param zs service handle.
+   
+   There should be one handle for each thread doing something
+   with zebra, be that searching or indexing. In simple apps 
+   one handle is sufficient 
 */
 YAZ_EXPORT
 ZebraHandle zebra_open(ZebraService zs);
 
-/** \fn int zebra_close(ZebraHandle zh)
-    \brief destroys Zebra session handle.
-    \param zh zebra session handle.
+/**
+   \brief Destroys Zebra session handle.
+   \param zh zebra session handle.
  */
 YAZ_EXPORT
 ZEBRA_RES zebra_close(ZebraHandle zh);
 
-/** \fn int zebra_errCode(ZebraHandle zh)
-    \brief returns error code for last error
-    \param zh zebra session handle.
+/**
+   \brief Returns error code for last error
+   \param zh zebra session handle.
 */
 YAZ_EXPORT
 int zebra_errCode(ZebraHandle zh);
 
-/** \fn const char *zebra_errString(ZebraHandle zh)
-    \brief returns error string for last error
-    \param zh zebra session handle.
+/**
+   \brief Returns error string for last error
+   \param zh zebra session handle.
 */
 YAZ_EXPORT
 const char *zebra_errString(ZebraHandle zh);
 
-/** \fn char *zebra_errAdd(ZebraHandle zh)
-    \brief returns additional info for last error
-    \param zh zebra session handle.
+/**
+   \brief Returns additional info for last error
+   \param zh zebra session handle.
 */
 YAZ_EXPORT
 char *zebra_errAdd(ZebraHandle zh);
 
-/** \fn int zebra_result(ZebraHandle zh, int *code, char **addinfo)
-    \brief returns error code and additional info for last error
-    \param zh zebra session handle.
-    \param code pointer to returned error code
-    \param addinfo pointer to returned additional info
+/**
+   \brief Returns error code and additional info for last error
+   \param zh zebra session handle.
+   \param code pointer to returned error code
+   \param addinfo pointer to returned additional info
 */
 YAZ_EXPORT
 void zebra_result(ZebraHandle zh, int *code, char **addinfo);
 
-/** \fn void zebra_clearError(ZebraHandle zh)
-    \brief clears last error.
+/** 
+    \brief Clears last error.
     \param zh zebra session handle.
- */
+*/
 YAZ_EXPORT
 void zebra_clearError(ZebraHandle zh);
 
-/** \fn ZEBRA_RES zebra_search_PQF(ZebraHandle zh, const char *pqf_query, \
-		const char *setname, zint *hits)
-    \brief Search using PQF Query 
-    \param zh session handle
-    \param pqf_query query
-    \param setname name of resultset
-    \param hits of hits is returned
+
+/**
+   \brief Set limit before Zebra does approx hit count
+   \param zh session handle
+   \param approx_limit the limit
+   
+   Results will be approximiate if hit count is greater than the
+   limit specified. By default there is a high-limit (no limit).
+*/
+ZEBRA_RES zebra_set_approx_limit(ZebraHandle zh, zint approx_limit);
+
+/**
+   \brief Search using PQF Query 
+   \param zh session handle
+   \param pqf_query query
+   \param setname name of resultset
+   \param hits of hits is returned
  */
 YAZ_EXPORT
 ZEBRA_RES zebra_search_PQF(ZebraHandle zh, const char *pqf_query,
@@ -206,7 +215,7 @@ ZEBRA_RES zebra_search_RPN(ZebraHandle zh, ODR o, Z_RPNQuery *query,
 		const char *setname, Z_RecordComposition *comp, \
 		oid_value input_format, int num_recs, \
 		ZebraRetrievalRecord *recs)
-    \brief retrieve records from result set (after search)
+    \brief Retrieve records from result set (after search)
     \param zh session handle
     \param stream allocate records returned using this ODR
     \param setname name of result set to retrieve records from
@@ -223,9 +232,7 @@ ZEBRA_RES zebra_records_retrieve(ZebraHandle zh, ODR stream,
 				 int num_recs,
 				 ZebraRetrievalRecord *recs);
 /**
-   \fn int zebra_deleteResultSet(ZebraHandle zh, int function, \
-		int num_setnames, char **setnames, int *statuses)
-   \brief delete one or more resultsets 
+   \brief Deletes one or more resultsets 
    \param zh session handle
    \param function Z_DeleteResultSetRequest_{list,all}
    \param num_setnames number of result sets
@@ -237,11 +244,48 @@ int zebra_deleteResultSet(ZebraHandle zh, int function,
 			  int num_setnames, char **setnames,
 			  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,
+				     char *termbuf, size_t *termlen,
+				     const char **term_ref_id);
+
+
 /**
-   \fn ZEBRA_RES zebra_scan(ZebraHandle zh, ODR stream, \
-		Z_AttributesPlusTerm *zapt, oid_value attributeset, \
-   		int *position, int *num_entries, ZebraScanEntry **list, \
-		int *is_partial)
    \brief performs Scan (Z39.50 style)
    \param zh session handle
    \param stream ODR handle for result
@@ -249,35 +293,35 @@ int zebra_deleteResultSet(ZebraHandle zh, int function,
    \param attributeset Attributeset for Attribute plus Term
    \param position input/output position
    \param num_entries number of terms requested / returned 
-   \param list list of resulting terms (ODR allocated)
+   \param entries list of resulting terms (ODR allocated)
    \param is_partial upon return 1=partial, 0=complete
+   \param setname limit scan by this set (NULL means no limit)
 */
 YAZ_EXPORT ZEBRA_RES zebra_scan(ZebraHandle zh, ODR stream,
 				Z_AttributesPlusTerm *zapt,
 				oid_value attributeset,
 				int *position, int *num_entries,
-				ZebraScanEntry **list,
-				int *is_partial);
+				ZebraScanEntry **entries,
+				int *is_partial,
+				const char *setname);
 
 /**
-   \fn ZEBRA_RES zebra_scan_PQF(ZebraHandle zh, ODR stream, \
-		const char *query, int *position, int *num_entries, \
-		ZebraScanEntry **list, int *is_partial)
    \brief performs Scan (taking PQF string)
    \param zh session handle
    \param stream ODR handle for result
    \param query PQF scan query
    \param position input/output position
    \param num_entries number of terms requested / returned 
-   \param list list of resulting terms (ODR allocated)
+   \param entries list of resulting terms (ODR allocated)
    \param is_partial upon return 1=partial, 0=complete
+   \param setname limit scan by this set (NULL means no limit)
 */
 YAZ_EXPORT
 ZEBRA_RES zebra_scan_PQF(ZebraHandle zh, ODR stream, const char *query,
 		    int *position, int *num_entries, ZebraScanEntry **entries,
-		    int *is_partial);
+		    int *is_partial, const char *setname);
+
 /**
-   \fn ZEBRA_RES zebra_auth(ZebraHandle zh, const char *user, const char *pass)
    \brief authenticate user. Returns 0 if OK, != 0 on failure
    \param zh session handle
    \param user user name
@@ -287,10 +331,7 @@ YAZ_EXPORT
 ZEBRA_RES zebra_auth(ZebraHandle zh, const char *user, const char *pass);
 
 /**
-   \fn int zebra_string_norm(ZebraHandle zh, unsigned reg_id, \
-		const char *input_str, int input_len, \
-		char *output_str, int output_len)
-   \brief normalize zebra term for register (subject to change!)
+   \brief Normalize zebra term for register (subject to change!)
    \param zh session handle
    \param reg_id register ID, 'w', 'p',..
    \param input_str input string buffer
@@ -303,8 +344,7 @@ int zebra_string_norm(ZebraHandle zh, unsigned reg_id, const char *input_str,
 		int input_len, char *output_str, int output_len);
 
 /**
-   \fn ZEBRA_RES zebra_create_database(ZebraHandle zh, const char *db)
-   \brief creates a database
+   \brief Creates a database
    \param zh session handle
    \param db database to be created
 */
@@ -312,8 +352,7 @@ YAZ_EXPORT
 ZEBRA_RES zebra_create_database(ZebraHandle zh, const char *db);
 
 /**
-   \fn int zebra_drop_database(ZebraHandle zh, const char *db)
-   \brief deletes a database (drop)
+   \brief Deletes a database (drop)
    \param zh session handle
    \param db database to be deleted
 */
@@ -397,11 +436,6 @@ ZEBRA_RES zebra_delete_record(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,
@@ -474,7 +508,11 @@ YAZ_END_CDECL
  * \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