include/yaz/zoom.h

   1 /*
   2  * Public header for ZOOM C.
   3  * $Id: zoom.h,v 1.7 2001-11-18 21:14:23 adam Exp $
   4  */
   5
   6 #include <yaz/yconfig.h>
   7
   8 #define ZOOM_EXPORT YAZ_EXPORT
   9 #define ZOOM_BEGIN_CDECL YAZ_BEGIN_CDECL
  10 #define ZOOM_END_CDECL YAZ_END_CDECL
  11
  12 ZOOM_BEGIN_CDECL
  13
  14 /* ----------------------------------------------------------- */
  15 /* the types we use */
  16
  17 typedef struct ZOOM_options_p *ZOOM_options;
  18 typedef struct ZOOM_query_p *ZOOM_query;
  19 typedef struct ZOOM_connection_p *ZOOM_connection;
  20 typedef struct ZOOM_resultset_p *ZOOM_resultset;
  21 typedef struct ZOOM_task_p *ZOOM_task;
  22 typedef struct ZOOM_record_p *ZOOM_record;
  23
  24 /* ----------------------------------------------------------- */
  25 /* connections */
  26
  27 /* create connection, connect to host, if portnum is 0, then port is
  28 read from host string (e.g. myhost:9821) */
  29 ZOOM_EXPORT
  30 ZOOM_connection ZOOM_connection_new (const char *host, int portnum);
  31
  32 /* create connection, don't connect, apply options */
  33 ZOOM_EXPORT
  34 ZOOM_connection ZOOM_connection_create (ZOOM_options options);
  35
  36 /* connect given existing connection */
  37 ZOOM_EXPORT
  38 void ZOOM_connection_connect(ZOOM_connection c, const char *host,
  39                               int portnum);
  40
  41 /* destroy connection (close connection also) */
  42 ZOOM_EXPORT
  43 void ZOOM_connection_destroy (ZOOM_connection c);
  44
  45 /* get/set option for connection */
  46 ZOOM_EXPORT
  47 const char *ZOOM_connection_option_get (ZOOM_connection c, const char *key);
  48
  49 ZOOM_EXPORT
  50 void ZOOM_connection_option_set (ZOOM_connection c, const char *key,
  51                                   const char *val);
  52
  53 /* return error code (0 == success, failure otherwise). cp
  54    holds error string on failure, addinfo holds addititional info (if any)
  55 */
  56 ZOOM_EXPORT
  57 int ZOOM_connection_error (ZOOM_connection c, const char **cp,
  58                             const char **addinfo);
  59
  60 /* returns error code */
  61 ZOOM_EXPORT
  62 int ZOOM_connection_errcode (ZOOM_connection c);
  63 /* returns error message */
  64 ZOOM_EXPORT
  65 const char *ZOOM_connection_errmsg (ZOOM_connection c);
  66 /* returns additional info */
  67 ZOOM_EXPORT
  68 const char *ZOOM_connection_addinfo (ZOOM_connection c);
  69
  70 #define ZOOM_ERROR_NONE 0
  71 #define ZOOM_ERROR_CONNECT 10000
  72 #define ZOOM_ERROR_MEMORY  10001
  73 #define ZOOM_ERROR_ENCODE  10002
  74 #define ZOOM_ERROR_DECODE  10003
  75 #define ZOOM_ERROR_CONNECTION_LOST 10004
  76 #define ZOOM_ERROR_INIT 10005
  77 #define ZOOM_ERROR_INTERNAL 10006
  78 #define ZOOM_ERROR_TIMEOUT 10007
  79
  80 /* ----------------------------------------------------------- */
  81 /* result sets */
  82
  83 /* create result set given a search */
  84 ZOOM_EXPORT
  85 ZOOM_resultset ZOOM_connection_search(ZOOM_connection, ZOOM_query q);
  86 /* create result set given PQF query */
  87 ZOOM_EXPORT
  88 ZOOM_resultset ZOOM_connection_search_pqf(ZOOM_connection c, const char *q);
  89
  90 /* destroy result set */
  91 ZOOM_EXPORT
  92 void ZOOM_resultset_destroy(ZOOM_resultset r);
  93
  94 /* result set option */
  95 ZOOM_EXPORT
  96 const char *ZOOM_resultset_option_get (ZOOM_resultset r, const char *key);
  97 ZOOM_EXPORT
  98 void ZOOM_resultset_option_set (ZOOM_resultset r, const char *key, const char *val);
  99
 100 /* return size of result set (alias hit count AKA result count) */
 101 ZOOM_EXPORT
 102 size_t ZOOM_resultset_size (ZOOM_resultset r);
 103
 104 /* retrieve records */
 105 ZOOM_EXPORT
 106 void ZOOM_resultset_records (ZOOM_resultset r, ZOOM_record *recs,
 107                               size_t start, size_t count);
 108
 109 /* return record object at pos. Returns 0 if unavailable */
 110 ZOOM_EXPORT
 111 ZOOM_record ZOOM_resultset_record (ZOOM_resultset s, size_t pos);
 112
 113 /* like ZOOM_resultset_record - but never blocks .. */
 114 ZOOM_EXPORT
 115 ZOOM_record ZOOM_resultset_record_immediate (ZOOM_resultset s, size_t pos);
 116
 117 /* ----------------------------------------------------------- */
 118 /* records */
 119
 120 /* get record information, in a form given by type */
 121 ZOOM_EXPORT
 122 void *ZOOM_record_get (ZOOM_record rec, const char *type, size_t *len);
 123
 124 /* destroy record */
 125 ZOOM_EXPORT
 126 void ZOOM_record_destroy (ZOOM_record rec);
 127
 128 /* return copy of record */
 129 ZOOM_EXPORT
 130 ZOOM_record ZOOM_record_clone (ZOOM_record srec);
 131
 132 /* ----------------------------------------------------------- */
 133 /* searches */
 134
 135 /* create search object */
 136 ZOOM_EXPORT
 137 ZOOM_query ZOOM_query_create(void);
 138 /* destroy it */
 139 ZOOM_EXPORT
 140 void ZOOM_query_destroy(ZOOM_query s);
 141 /* specify prefix query for search */
 142 ZOOM_EXPORT
 143 int ZOOM_query_prefix(ZOOM_query s, const char *str);
 144 /* specify sort criteria for search */
 145 ZOOM_EXPORT
 146 int ZOOM_query_sortby(ZOOM_query s, const char *criteria);
 147
 148 /* ----------------------------------------------------------- */
 149 /* options */
 150 typedef const char *(*ZOOM_options_callback)(void *handle, const char *name);
 151
 152 ZOOM_EXPORT
 153 ZOOM_options_callback ZOOM_options_set_callback (ZOOM_options opt,
 154                                                    ZOOM_options_callback c,
 155                                                    void *handle);
 156 ZOOM_EXPORT
 157 ZOOM_options ZOOM_options_create (void);
 158
 159 ZOOM_EXPORT
 160 ZOOM_options ZOOM_options_create_with_parent (ZOOM_options parent);
 161
 162 ZOOM_EXPORT
 163 const char *ZOOM_options_get (ZOOM_options opt, const char *name);
 164
 165 ZOOM_EXPORT
 166 void ZOOM_options_set (ZOOM_options opt, const char *name, const char *v);
 167
 168 ZOOM_EXPORT
 169 void ZOOM_options_destroy (ZOOM_options opt);
 170
 171 ZOOM_EXPORT
 172 int ZOOM_options_get_bool (ZOOM_options opt, const char *name, int defa);
 173
 174 ZOOM_EXPORT
 175 int ZOOM_options_get_int (ZOOM_options opt, const char *name, int defa);
 176
 177 ZOOM_EXPORT
 178 void ZOOM_options_addref (ZOOM_options opt);
 179
 180 /* ----------------------------------------------------------- */
 181 /* events */
 182 /* poll for events on a number of connections. Returns positive
 183    integer if event occurred ; zero if none occurred and no more
 184    events are pending. The positive integer specifies the
 185    connection for which the event occurred. There's no way to get
 186    the details yet, sigh. */
 187 ZOOM_EXPORT
 188 int ZOOM_event (int no, ZOOM_connection *cs);
 189
 190 ZOOM_END_CDECL