include/yaz/zoom.h

   1 /*
   2  * Public header for ZOOM C.
   3  * $Id: zoom.h,v 1.5 2001-11-15 13:16:02 adam Exp $
   4  */
   5
   6 /* 1. Renamed type Z3950_search to Z3950_query and the functions
   7       that manipulate it..
   8       Changed positions/sizes to be of type size_t rather than int.
   9    2. Deleted Z3950_resultset_get. Added Z3950_record_dup. Record
  10       reference(s) returned by Z350_resultset_records and
  11       Z3950_resultset_record are "owned" by result set.
  12 */
  13 #include <yaz/yconfig.h>
  14
  15 #define ZOOM_EXPORT YAZ_EXPORT
  16 #define ZOOM_BEGIN_CDECL YAZ_BEGIN_CDECL
  17 #define ZOOM_END_CDECL YAZ_END_CDECL
  18
  19 ZOOM_BEGIN_CDECL
  20
  21 /* ----------------------------------------------------------- */
  22 /* the types we use */
  23
  24 typedef struct Z3950_options_p *Z3950_options;
  25 typedef struct Z3950_query_p *Z3950_query;
  26 typedef struct Z3950_connection_p *Z3950_connection;
  27 typedef struct Z3950_resultset_p *Z3950_resultset;
  28 typedef struct Z3950_task_p *Z3950_task;
  29 typedef struct Z3950_record_p *Z3950_record;
  30
  31 /* ----------------------------------------------------------- */
  32 /* connections */
  33
  34 /* create connection, connect to host, if portnum is 0, then port is
  35 read from host string (e.g. myhost:9821) */
  36 ZOOM_EXPORT
  37 Z3950_connection Z3950_connection_new (const char *host, int portnum);
  38
  39 /* create connection, don't connect, apply options */
  40 ZOOM_EXPORT
  41 Z3950_connection Z3950_connection_create (Z3950_options options);
  42
  43 /* connect given existing connection */
  44 ZOOM_EXPORT
  45 void Z3950_connection_connect(Z3950_connection c, const char *host,
  46                               int portnum);
  47
  48 /* destroy connection (close connection also) */
  49 ZOOM_EXPORT
  50 void Z3950_connection_destroy (Z3950_connection c);
  51
  52 /* get/set option for connection */
  53 ZOOM_EXPORT
  54 const char *Z3950_connection_option_get (Z3950_connection c, const char *key);
  55
  56 ZOOM_EXPORT
  57 void Z3950_connection_option_set (Z3950_connection c, const char *key,
  58                                   const char *val);
  59 /* return host for connection */
  60 ZOOM_EXPORT
  61 const char *Z3950_connection_host (Z3950_connection c);
  62
  63 /* return error code (0 == success, failure otherwise). cp
  64    holds error string on failure, addinfo holds addititional info (if any)
  65 */
  66 ZOOM_EXPORT
  67 int Z3950_connection_error (Z3950_connection c, const char **cp,
  68                             const char **addinfo);
  69
  70 /* returns error code */
  71 ZOOM_EXPORT
  72 int Z3950_connection_errcode (Z3950_connection c);
  73 /* returns error message */
  74 ZOOM_EXPORT
  75 const char *Z3950_connection_errmsg (Z3950_connection c);
  76 /* returns additional info */
  77 ZOOM_EXPORT
  78 const char *Z3950_connection_addinfo (Z3950_connection c);
  79
  80 #define Z3950_ERROR_NONE 0
  81 #define Z3950_ERROR_CONNECT 10000
  82 #define Z3950_ERROR_MEMORY  10001
  83 #define Z3950_ERROR_ENCODE  10002
  84 #define Z3950_ERROR_DECODE  10003
  85 #define Z3950_ERROR_CONNECTION_LOST 10004
  86 #define Z3950_ERROR_INIT 10005
  87 #define Z3950_ERROR_INTERNAL 10006
  88 #define Z3950_ERROR_TIMEOUT 10007
  89
  90 /* ----------------------------------------------------------- */
  91 /* result sets */
  92
  93 /* create result set given a search */
  94 ZOOM_EXPORT
  95 Z3950_resultset Z3950_connection_search(Z3950_connection, Z3950_query q);
  96 /* create result set given PQF query */
  97 ZOOM_EXPORT
  98 Z3950_resultset Z3950_connection_search_pqf(Z3950_connection c, const char *q);
  99
 100 /* destroy result set */
 101 ZOOM_EXPORT
 102 void Z3950_resultset_destroy(Z3950_resultset r);
 103
 104 /* result set option */
 105 ZOOM_EXPORT
 106 const char *Z3950_resultset_option_get (Z3950_resultset r, const char *key);
 107 ZOOM_EXPORT
 108 void Z3950_resultset_option_set (Z3950_resultset r, const char *key, const char *val);
 109
 110 /* return size of result set (alias hit count AKA result count) */
 111 ZOOM_EXPORT
 112 size_t Z3950_resultset_size (Z3950_resultset r);
 113
 114 /* retrieve records */
 115 ZOOM_EXPORT
 116 void Z3950_resultset_records (Z3950_resultset r, Z3950_record *recs,
 117                               size_t start, size_t count);
 118
 119 /* return record object at pos. Returns 0 if unavailable */
 120 ZOOM_EXPORT
 121 Z3950_record Z3950_resultset_record (Z3950_resultset s, size_t pos);
 122
 123 /* like Z3950_resultset_record - but never blocks .. */
 124 ZOOM_EXPORT
 125 Z3950_record Z3950_resultset_record_immediate (Z3950_resultset s, size_t pos);
 126
 127 /* ----------------------------------------------------------- */
 128 /* records */
 129
 130 /* get record information, in a form given by type */
 131 ZOOM_EXPORT
 132 void *Z3950_record_get (Z3950_record rec, const char *type, size_t *len);
 133
 134 /* destroy record */
 135 ZOOM_EXPORT
 136 void Z3950_record_destroy (Z3950_record rec);
 137
 138 /* return copy of record */
 139 ZOOM_EXPORT
 140 Z3950_record Z3950_record_dup (Z3950_record srec);
 141
 142 /* ----------------------------------------------------------- */
 143 /* searches */
 144
 145 /* create search object */
 146 ZOOM_EXPORT
 147 Z3950_query Z3950_query_create(void);
 148 /* destroy it */
 149 ZOOM_EXPORT
 150 void Z3950_query_destroy(Z3950_query s);
 151 /* specify prefix query for search */
 152 ZOOM_EXPORT
 153 int Z3950_query_prefix(Z3950_query s, const char *str);
 154 /* specify sort criteria for search */
 155 ZOOM_EXPORT
 156 int Z3950_query_sortby(Z3950_query s, const char *criteria);
 157
 158 /* ----------------------------------------------------------- */
 159 /* options */
 160 typedef const char *(*Z3950_options_callback)(void *handle, const char *name);
 161
 162 ZOOM_EXPORT
 163 Z3950_options_callback Z3950_options_set_callback (Z3950_options opt,
 164                                                    Z3950_options_callback c,
 165                                                    void *handle);
 166 ZOOM_EXPORT
 167 Z3950_options Z3950_options_create (void);
 168
 169 ZOOM_EXPORT
 170 Z3950_options Z3950_options_create_with_parent (Z3950_options parent);
 171
 172 ZOOM_EXPORT
 173 const char *Z3950_options_get (Z3950_options opt, const char *name);
 174
 175 ZOOM_EXPORT
 176 void Z3950_options_set (Z3950_options opt, const char *name, const char *v);
 177
 178 ZOOM_EXPORT
 179 void Z3950_options_destroy (Z3950_options opt);
 180
 181 ZOOM_EXPORT
 182 int Z3950_options_get_bool (Z3950_options opt, const char *name, int defa);
 183
 184 ZOOM_EXPORT
 185 int Z3950_options_get_int (Z3950_options opt, const char *name, int defa);
 186
 187 ZOOM_EXPORT
 188 void Z3950_options_addref (Z3950_options opt);
 189
 190 /* ----------------------------------------------------------- */
 191 /* events */
 192 /* poll for events on a number of connections. Returns positive
 193    integer if event occurred ; zero if none occurred and no more
 194    events are pending. The positive integer specifies the
 195    connection for which the event occurred. There's no way to get
 196    the details yet, sigh. */
 197 ZOOM_EXPORT
 198 int Z3950_event (int no, Z3950_connection *cs);
 199
 200 ZOOM_END_CDECL