include/yaz/zoom.h

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