include/yaz/zoom.h

   1 /*
   2  * Public header for ZOOM C.
   3  * $Id: zoom.h,v 1.4 2001-11-15 08:58:29 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 /* set option for connection */
  53 ZOOM_EXPORT
  54 const char *Z3950_connection_option (Z3950_connection c, const char *key,
  55                                      const char *val);
  56 /* return host for connection */
  57 ZOOM_EXPORT
  58 const char *Z3950_connection_host (Z3950_connection c);
  59
  60 /* return error code (0 == success, failure otherwise). cp
  61    holds error string on failure, addinfo holds addititional info (if any)
  62 */
  63 ZOOM_EXPORT
  64 int Z3950_connection_error (Z3950_connection c, const char **cp,
  65                             const char **addinfo);
  66
  67 /* returns error code */
  68 ZOOM_EXPORT
  69 int Z3950_connection_errcode (Z3950_connection c);
  70 /* returns error message */
  71 ZOOM_EXPORT
  72 const char *Z3950_connection_errmsg (Z3950_connection c);
  73 /* returns additional info */
  74 ZOOM_EXPORT
  75 const char *Z3950_connection_addinfo (Z3950_connection c);
  76
  77 #define Z3950_ERROR_NONE 0
  78 #define Z3950_ERROR_CONNECT 10000
  79 #define Z3950_ERROR_MEMORY  10001
  80 #define Z3950_ERROR_ENCODE  10002
  81 #define Z3950_ERROR_DECODE  10003
  82 #define Z3950_ERROR_CONNECTION_LOST 10004
  83 #define Z3950_ERROR_INIT 10005
  84 #define Z3950_ERROR_INTERNAL 10006
  85 #define Z3950_ERROR_TIMEOUT 10007
  86
  87 /* ----------------------------------------------------------- */
  88 /* result sets */
  89
  90 /* create result set given a search */
  91 ZOOM_EXPORT
  92 Z3950_resultset Z3950_connection_search(Z3950_connection, Z3950_query q);
  93 /* create result set given PQF query */
  94 ZOOM_EXPORT
  95 Z3950_resultset Z3950_connection_search_pqf(Z3950_connection c, const char *q);
  96
  97 /* destroy result set */
  98 ZOOM_EXPORT
  99 void Z3950_resultset_destroy(Z3950_resultset r);
 100
 101 /* result set option */
 102 ZOOM_EXPORT
 103 const char *Z3950_resultset_option (Z3950_resultset r, const char *key,
 104                                     const char *val);
 105 /* return size of result set (alias hit count AKA result count) */
 106 ZOOM_EXPORT
 107 size_t Z3950_resultset_size (Z3950_resultset r);
 108
 109 /* retrieve records */
 110 ZOOM_EXPORT
 111 void Z3950_resultset_records (Z3950_resultset r, Z3950_record *recs,
 112                               size_t start, size_t count);
 113
 114 /* return record object at pos. Returns 0 if unavailable */
 115 ZOOM_EXPORT
 116 Z3950_record Z3950_resultset_record (Z3950_resultset s, size_t pos);
 117
 118 /* like Z3950_resultset_record - but never blocks .. */
 119 ZOOM_EXPORT
 120 Z3950_record Z3950_resultset_record_immediate (Z3950_resultset s, size_t pos);
 121
 122 /* ----------------------------------------------------------- */
 123 /* records */
 124
 125 /* get record information, in a form given by type */
 126 ZOOM_EXPORT
 127 void *Z3950_record_get (Z3950_record rec, const char *type, size_t *len);
 128
 129 /* destroy record */
 130 ZOOM_EXPORT
 131 void Z3950_record_destroy (Z3950_record rec);
 132
 133 /* return copy of record */
 134 ZOOM_EXPORT
 135 Z3950_record Z3950_record_dup (Z3950_record srec);
 136
 137 /* ----------------------------------------------------------- */
 138 /* searches */
 139
 140 /* create search object */
 141 ZOOM_EXPORT
 142 Z3950_query Z3950_query_create(void);
 143 /* destroy it */
 144 ZOOM_EXPORT
 145 void Z3950_query_destroy(Z3950_query s);
 146 /* specify prefix query for search */
 147 ZOOM_EXPORT
 148 int Z3950_query_prefix(Z3950_query s, const char *str);
 149 /* specify sort criteria for search */
 150 ZOOM_EXPORT
 151 int Z3950_query_sortby(Z3950_query s, const char *criteria);
 152
 153 /* ----------------------------------------------------------- */
 154 /* options */
 155 typedef const char *(*Z3950_options_callback)(void *handle, const char *name);
 156
 157 ZOOM_EXPORT
 158 Z3950_options_callback Z3950_options_set_callback (Z3950_options opt,
 159                                                    Z3950_options_callback c,
 160                                                    void *handle);
 161 ZOOM_EXPORT
 162 Z3950_options Z3950_options_create (void);
 163
 164 ZOOM_EXPORT
 165 Z3950_options Z3950_options_create_with_parent (Z3950_options parent);
 166
 167 ZOOM_EXPORT
 168 const char *Z3950_options_get (Z3950_options opt, const char *name);
 169
 170 ZOOM_EXPORT
 171 void Z3950_options_set (Z3950_options opt, const char *name, const char *v);
 172
 173 ZOOM_EXPORT
 174 void Z3950_options_destroy (Z3950_options opt);
 175
 176 ZOOM_EXPORT
 177 int Z3950_options_get_bool (Z3950_options opt, const char *name, int defa);
 178
 179 ZOOM_EXPORT
 180 int Z3950_options_get_int (Z3950_options opt, const char *name, int defa);
 181
 182 ZOOM_EXPORT
 183 void Z3950_options_addref (Z3950_options opt);
 184
 185 /* ----------------------------------------------------------- */
 186 /* events */
 187 /* poll for events on a number of connections. Returns positive
 188    integer if event occurred ; zero if none occurred and no more
 189    events are pending. The positive integer specifies the
 190    connection for which the event occurred. There's no way to get
 191    the details yet, sigh. */
 192 ZOOM_EXPORT
 193 int Z3950_event (int no, Z3950_connection *cs);
 194
 195 ZOOM_END_CDECL