include/yaz/zoom.h

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