include/yaz/zoom.h

   1 /*
   2  * Public header for ZOOM C.
   3  * $Id: zoom.h,v 1.1 2001-10-23 21:00:19 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 Z3950_connection Z3950_connection_new (const char *host, int portnum);
  24
  25 /* create connection, don't connect, apply options */
  26 Z3950_connection Z3950_connection_create (Z3950_options options);
  27
  28 /* connect given existing connection */
  29 void Z3950_connection_connect(Z3950_connection c, const char *host,
  30                               int portnum);
  31
  32 /* destroy connection (close connection also *) */
  33 void Z3950_connection_destroy (Z3950_connection c);
  34
  35 /* set option for connection */
  36 const char *Z3950_connection_option (Z3950_connection c, const char *key,
  37                                      const char *val);
  38 /* return host for connection */
  39 const char *Z3950_connection_host (Z3950_connection c);
  40
  41 /* return error code (0 == success, failure otherwise). cp
  42    holds error string on failure, addinfo holds addititional info (if any)
  43 */
  44 int Z3950_connection_error (Z3950_connection c, const char **cp,
  45                             const char **addinfo);
  46
  47 /* returns error code */
  48 int Z3950_connection_errcode (Z3950_connection c);
  49 /* returns error message */
  50 const char *Z3950_connection_errmsg (Z3950_connection c);
  51 /* returns additional info */
  52 const char *Z3950_connection_addinfo (Z3950_connection c);
  53
  54 #define Z3950_ERROR_NONE 0
  55 #define Z3950_ERROR_CONNECT 10000
  56 #define Z3950_ERROR_MEMORY  10001
  57 #define Z3950_ERROR_ENCODE  10002
  58 #define Z3950_ERROR_DECODE  10003
  59 #define Z3950_ERROR_CONNECTION_LOST 10004
  60 #define Z3950_ERROR_INIT 10005
  61 #define Z3950_ERROR_INTERNAL 10006
  62 #define Z3950_ERROR_TIMEOUT 10007
  63
  64 /* ----------------------------------------------------------- */
  65 /* result sets */
  66
  67 /* create result set given a search */
  68 Z3950_resultset Z3950_connection_search(Z3950_connection, Z3950_search q);
  69 /* create result set given PQF query */
  70 Z3950_resultset Z3950_connection_search_pqf(Z3950_connection c, const char *q);
  71
  72 /* destroy result set */
  73 void Z3950_resultset_destroy(Z3950_resultset r);
  74
  75 /* result set option */
  76 const char *Z3950_resultset_option (Z3950_resultset r, const char *key,
  77                                     const char *val);
  78 /* return size of result set (hit count, AKA resultCount) */
  79 int Z3950_resultset_size (Z3950_resultset r);
  80
  81 /* return record at pos (starting from ), render given spec in type */
  82 void *Z3950_resultset_get (Z3950_resultset s, int pos, const char *type,
  83                            int *len);
  84 /* retrieve records */
  85 void Z3950_resultset_records (Z3950_resultset r, Z3950_record *recs,
  86                               size_t *cnt);
  87
  88 /* return record object at pos. Returns 0 if unavailable */
  89 Z3950_record Z3950_resultset_record (Z3950_resultset s, int pos);
  90
  91 /* like Z3950_resultset_record - but never blocks .. */
  92 Z3950_record Z3950_resultset_record_immediate (Z3950_resultset s, int pos);
  93
  94 /* ----------------------------------------------------------- */
  95 /* records */
  96
  97 /* Get record information, in a form given by type */
  98 void *Z3950_record_get (Z3950_record rec, const char *type, int *len);
  99
 100 /* Destroy record */
 101 void Z3950_record_destroy (Z3950_record rec);
 102
 103 /* ----------------------------------------------------------- */
 104 /* searches */
 105
 106 /* create search object */
 107 Z3950_search Z3950_search_create(void);
 108 /* destroy it */
 109 void Z3950_search_destroy(Z3950_search s);
 110 /* specify prefix query for search */
 111 int Z3950_search_prefix(Z3950_search s, const char *str);
 112 /* specify sort criteria for search */
 113 int Z3950_search_sortby(Z3950_search s, const char *criteria);
 114
 115
 116 /* ----------------------------------------------------------- */
 117 /* options */
 118 typedef const char *(*Z3950_options_callback)(void *handle, const char *name);
 119
 120 Z3950_options_callback Z3950_options_set_callback (Z3950_options opt,
 121                                                    Z3950_options_callback c,
 122                                                    void *handle);
 123 Z3950_options Z3950_options_create (void);
 124 Z3950_options Z3950_options_create_with_parent (Z3950_options parent);
 125 const char *Z3950_options_get (Z3950_options opt, const char *name);
 126 void Z3950_options_set (Z3950_options opt, const char *name, const char *v);
 127 void Z3950_options_destroy (Z3950_options opt);
 128 int Z3950_options_get_bool (Z3950_options opt, const char *name, int defa);
 129 int Z3950_options_get_int (Z3950_options opt, const char *name, int defa);
 130 void Z3950_options_addref (Z3950_options opt);
 131
 132 /* ----------------------------------------------------------- */
 133 /* events */
 134 /* poll for events on a number of connections. Returns positive
 135    integer if event occurred ; zero if none occurred and no more
 136    events are pending. The positive integer specifies the
 137    connection for which the event occurred. There's no way to get
 138    the details yet, sigh. */
 139 int Z3950_event (int no, Z3950_connection *cs);
 140
 141 YAZ_END_CDECL