2 * Public header for ZOOM C.
3 * $Id: zoom.h,v 1.5 2001-11-15 13:16:02 adam Exp $
6 /* 1. Renamed type Z3950_search to Z3950_query and the functions
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.
13 #include <yaz/yconfig.h>
15 #define ZOOM_EXPORT YAZ_EXPORT
16 #define ZOOM_BEGIN_CDECL YAZ_BEGIN_CDECL
17 #define ZOOM_END_CDECL YAZ_END_CDECL
21 /* ----------------------------------------------------------- */
22 /* the types we use */
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;
31 /* ----------------------------------------------------------- */
34 /* create connection, connect to host, if portnum is 0, then port is
35 read from host string (e.g. myhost:9821) */
37 Z3950_connection Z3950_connection_new (const char *host, int portnum);
39 /* create connection, don't connect, apply options */
41 Z3950_connection Z3950_connection_create (Z3950_options options);
43 /* connect given existing connection */
45 void Z3950_connection_connect(Z3950_connection c, const char *host,
48 /* destroy connection (close connection also) */
50 void Z3950_connection_destroy (Z3950_connection c);
52 /* get/set option for connection */
54 const char *Z3950_connection_option_get (Z3950_connection c, const char *key);
57 void Z3950_connection_option_set (Z3950_connection c, const char *key,
59 /* return host for connection */
61 const char *Z3950_connection_host (Z3950_connection c);
63 /* return error code (0 == success, failure otherwise). cp
64 holds error string on failure, addinfo holds addititional info (if any)
67 int Z3950_connection_error (Z3950_connection c, const char **cp,
68 const char **addinfo);
70 /* returns error code */
72 int Z3950_connection_errcode (Z3950_connection c);
73 /* returns error message */
75 const char *Z3950_connection_errmsg (Z3950_connection c);
76 /* returns additional info */
78 const char *Z3950_connection_addinfo (Z3950_connection c);
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
90 /* ----------------------------------------------------------- */
93 /* create result set given a search */
95 Z3950_resultset Z3950_connection_search(Z3950_connection, Z3950_query q);
96 /* create result set given PQF query */
98 Z3950_resultset Z3950_connection_search_pqf(Z3950_connection c, const char *q);
100 /* destroy result set */
102 void Z3950_resultset_destroy(Z3950_resultset r);
104 /* result set option */
106 const char *Z3950_resultset_option_get (Z3950_resultset r, const char *key);
108 void Z3950_resultset_option_set (Z3950_resultset r, const char *key, const char *val);
110 /* return size of result set (alias hit count AKA result count) */
112 size_t Z3950_resultset_size (Z3950_resultset r);
114 /* retrieve records */
116 void Z3950_resultset_records (Z3950_resultset r, Z3950_record *recs,
117 size_t start, size_t count);
119 /* return record object at pos. Returns 0 if unavailable */
121 Z3950_record Z3950_resultset_record (Z3950_resultset s, size_t pos);
123 /* like Z3950_resultset_record - but never blocks .. */
125 Z3950_record Z3950_resultset_record_immediate (Z3950_resultset s, size_t pos);
127 /* ----------------------------------------------------------- */
130 /* get record information, in a form given by type */
132 void *Z3950_record_get (Z3950_record rec, const char *type, size_t *len);
136 void Z3950_record_destroy (Z3950_record rec);
138 /* return copy of record */
140 Z3950_record Z3950_record_dup (Z3950_record srec);
142 /* ----------------------------------------------------------- */
145 /* create search object */
147 Z3950_query Z3950_query_create(void);
150 void Z3950_query_destroy(Z3950_query s);
151 /* specify prefix query for search */
153 int Z3950_query_prefix(Z3950_query s, const char *str);
154 /* specify sort criteria for search */
156 int Z3950_query_sortby(Z3950_query s, const char *criteria);
158 /* ----------------------------------------------------------- */
160 typedef const char *(*Z3950_options_callback)(void *handle, const char *name);
163 Z3950_options_callback Z3950_options_set_callback (Z3950_options opt,
164 Z3950_options_callback c,
167 Z3950_options Z3950_options_create (void);
170 Z3950_options Z3950_options_create_with_parent (Z3950_options parent);
173 const char *Z3950_options_get (Z3950_options opt, const char *name);
176 void Z3950_options_set (Z3950_options opt, const char *name, const char *v);
179 void Z3950_options_destroy (Z3950_options opt);
182 int Z3950_options_get_bool (Z3950_options opt, const char *name, int defa);
185 int Z3950_options_get_int (Z3950_options opt, const char *name, int defa);
188 void Z3950_options_addref (Z3950_options opt);
190 /* ----------------------------------------------------------- */
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. */
198 int Z3950_event (int no, Z3950_connection *cs);