include/yaz/zoom.h

   1 /*
   2  * Public header for ZOOM C.
   3  * $Id: zoom.h,v 1.6 2001-11-16 09:52:39 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 Z3950_options_p *Z3950_options;
  18 typedef struct Z3950_query_p *Z3950_query;
  19 typedef struct Z3950_connection_p *Z3950_connection;
  20 typedef struct Z3950_resultset_p *Z3950_resultset;
  21 typedef struct Z3950_task_p *Z3950_task;
  22 typedef struct Z3950_record_p *Z3950_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 Z3950_connection Z3950_connection_new (const char *host, int portnum);
  31
  32 /* create connection, don't connect, apply options */
  33 ZOOM_EXPORT
  34 Z3950_connection Z3950_connection_create (Z3950_options options);
  35
  36 /* connect given existing connection */
  37 ZOOM_EXPORT
  38 void Z3950_connection_connect(Z3950_connection c, const char *host,
  39                               int portnum);
  40
  41 /* destroy connection (close connection also) */
  42 ZOOM_EXPORT
  43 void Z3950_connection_destroy (Z3950_connection c);
  44
  45 /* get/set option for connection */
  46 ZOOM_EXPORT
  47 const char *Z3950_connection_option_get (Z3950_connection c, const char *key);
  48
  49 ZOOM_EXPORT
  50 void Z3950_connection_option_set (Z3950_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 Z3950_connection_error (Z3950_connection c, const char **cp,
  58                             const char **addinfo);
  59
  60 /* returns error code */
  61 ZOOM_EXPORT
  62 int Z3950_connection_errcode (Z3950_connection c);
  63 /* returns error message */
  64 ZOOM_EXPORT
  65 const char *Z3950_connection_errmsg (Z3950_connection c);
  66 /* returns additional info */
  67 ZOOM_EXPORT
  68 const char *Z3950_connection_addinfo (Z3950_connection c);
  69
  70 #define Z3950_ERROR_NONE 0
  71 #define Z3950_ERROR_CONNECT 10000
  72 #define Z3950_ERROR_MEMORY  10001
  73 #define Z3950_ERROR_ENCODE  10002
  74 #define Z3950_ERROR_DECODE  10003
  75 #define Z3950_ERROR_CONNECTION_LOST 10004
  76 #define Z3950_ERROR_INIT 10005
  77 #define Z3950_ERROR_INTERNAL 10006
  78 #define Z3950_ERROR_TIMEOUT 10007
  79
  80 /* ----------------------------------------------------------- */
  81 /* result sets */
  82
  83 /* create result set given a search */
  84 ZOOM_EXPORT
  85 Z3950_resultset Z3950_connection_search(Z3950_connection, Z3950_query q);
  86 /* create result set given PQF query */
  87 ZOOM_EXPORT
  88 Z3950_resultset Z3950_connection_search_pqf(Z3950_connection c, const char *q);
  89
  90 /* destroy result set */
  91 ZOOM_EXPORT
  92 void Z3950_resultset_destroy(Z3950_resultset r);
  93
  94 /* result set option */
  95 ZOOM_EXPORT
  96 const char *Z3950_resultset_option_get (Z3950_resultset r, const char *key);
  97 ZOOM_EXPORT
  98 void Z3950_resultset_option_set (Z3950_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 Z3950_resultset_size (Z3950_resultset r);
 103
 104 /* retrieve records */
 105 ZOOM_EXPORT
 106 void Z3950_resultset_records (Z3950_resultset r, Z3950_record *recs,
 107                               size_t start, size_t count);
 108
 109 /* return record object at pos. Returns 0 if unavailable */
 110 ZOOM_EXPORT
 111 Z3950_record Z3950_resultset_record (Z3950_resultset s, size_t pos);
 112
 113 /* like Z3950_resultset_record - but never blocks .. */
 114 ZOOM_EXPORT
 115 Z3950_record Z3950_resultset_record_immediate (Z3950_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 *Z3950_record_get (Z3950_record rec, const char *type, size_t *len);
 123
 124 /* destroy record */
 125 ZOOM_EXPORT
 126 void Z3950_record_destroy (Z3950_record rec);
 127
 128 /* return copy of record */
 129 ZOOM_EXPORT
 130 Z3950_record Z3950_record_dup (Z3950_record srec);
 131
 132 /* ----------------------------------------------------------- */
 133 /* searches */
 134
 135 /* create search object */
 136 ZOOM_EXPORT
 137 Z3950_query Z3950_query_create(void);
 138 /* destroy it */
 139 ZOOM_EXPORT
 140 void Z3950_query_destroy(Z3950_query s);
 141 /* specify prefix query for search */
 142 ZOOM_EXPORT
 143 int Z3950_query_prefix(Z3950_query s, const char *str);
 144 /* specify sort criteria for search */
 145 ZOOM_EXPORT
 146 int Z3950_query_sortby(Z3950_query s, const char *criteria);
 147
 148 /* ----------------------------------------------------------- */
 149 /* options */
 150 typedef const char *(*Z3950_options_callback)(void *handle, const char *name);
 151
 152 ZOOM_EXPORT
 153 Z3950_options_callback Z3950_options_set_callback (Z3950_options opt,
 154                                                    Z3950_options_callback c,
 155                                                    void *handle);
 156 ZOOM_EXPORT
 157 Z3950_options Z3950_options_create (void);
 158
 159 ZOOM_EXPORT
 160 Z3950_options Z3950_options_create_with_parent (Z3950_options parent);
 161
 162 ZOOM_EXPORT
 163 const char *Z3950_options_get (Z3950_options opt, const char *name);
 164
 165 ZOOM_EXPORT
 166 void Z3950_options_set (Z3950_options opt, const char *name, const char *v);
 167
 168 ZOOM_EXPORT
 169 void Z3950_options_destroy (Z3950_options opt);
 170
 171 ZOOM_EXPORT
 172 int Z3950_options_get_bool (Z3950_options opt, const char *name, int defa);
 173
 174 ZOOM_EXPORT
 175 int Z3950_options_get_int (Z3950_options opt, const char *name, int defa);
 176
 177 ZOOM_EXPORT
 178 void Z3950_options_addref (Z3950_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 Z3950_event (int no, Z3950_connection *cs);
 189
 190 ZOOM_END_CDECL