YAZ: zoom.h Source File

00001 /* This file is part of the YAZ toolkit.
00002  * Copyright (C) 1995-2008 Index Data.
00003  * All rights reserved.
00004  * Redistribution and use in source and binary forms, with or without
00005  * modification, are permitted provided that the following conditions are met:
00006  *
00007  *     * Redistributions of source code must retain the above copyright
00008  *       notice, this list of conditions and the following disclaimer.
00009  *     * Redistributions in binary form must reproduce the above copyright
00010  *       notice, this list of conditions and the following disclaimer in the
00011  *       documentation and/or other materials provided with the distribution.
00012  *     * Neither the name of Index Data nor the names of its contributors
00013  *       may be used to endorse or promote products derived from this
00014  *       software without specific prior written permission.
00015  *
00016  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY
00017  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00018  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00019  * DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY
00020  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00021  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00022  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
00023  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00024  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
00025  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00026  */
00027 
00033 #include <stdlib.h>
00034 #include <yaz/yconfig.h>
00035 
00036 #define ZOOM_BEGIN_CDECL YAZ_BEGIN_CDECL
00037 #define ZOOM_END_CDECL YAZ_END_CDECL
00038 
00039 #ifdef WIN32
00040 #  define ZOOM_API(x) __declspec(dllexport) x __stdcall
00041 #else
00042 #  define ZOOM_API(x) x
00043 # endif
00044 
00045 ZOOM_BEGIN_CDECL
00046 
00047 /* ----------------------------------------------------------- */
00048 /* the types we use */
00049 
00050 typedef struct ZOOM_options_p *ZOOM_options;
00051 typedef struct ZOOM_query_p *ZOOM_query;
00052 typedef struct ZOOM_connection_p *ZOOM_connection;
00053 typedef struct ZOOM_resultset_p *ZOOM_resultset;
00054 typedef struct ZOOM_record_p *ZOOM_record;
00055 typedef struct ZOOM_scanset_p *ZOOM_scanset;
00056 typedef struct ZOOM_package_p *ZOOM_package;
00057 
00058 typedef const char *(*ZOOM_options_callback)(void *handle, const char *name);
00059 
00060 /* ----------------------------------------------------------- */
00061 /* connections */
00062 
00063 /* create connection, connect to host, if portnum is 0, then port is
00064 read from host string (e.g. myhost:9821) */
00065 ZOOM_API(ZOOM_connection)
00066 ZOOM_connection_new (const char *host, int portnum);
00067 
00068 /* create connection, don't connect, apply options */
00069 ZOOM_API(ZOOM_connection)
00070 ZOOM_connection_create (ZOOM_options options);
00071 
00072 /* connect given existing connection */
00073 ZOOM_API(void)
00074 ZOOM_connection_connect(ZOOM_connection c, const char *host,
00075                               int portnum);
00076 
00077 /* destroy connection (close connection also) */
00078 ZOOM_API(void)
00079 ZOOM_connection_destroy (ZOOM_connection c);
00080 
00081 /* get/set option for connection */
00082 ZOOM_API(const char *)
00083 ZOOM_connection_option_get (ZOOM_connection c, const char *key);
00084 
00085 ZOOM_API(const char *)
00086 ZOOM_connection_option_getl (ZOOM_connection c, const char *key, int *lenp);
00087 
00088 ZOOM_API(void)
00089 ZOOM_connection_option_set (ZOOM_connection c, const char *key,
00090                             const char *val);
00091 
00092 ZOOM_API(void)
00093 ZOOM_connection_option_setl (ZOOM_connection c, const char *key,
00094                              const char *val, int len);
00095 
00096 /* return error code (0 == success, failure otherwise). cp
00097    holds error string on failure, addinfo holds addititional info (if any)
00098 */
00099 ZOOM_API(int)
00100 ZOOM_connection_error (ZOOM_connection c, const char **cp,
00101                             const char **addinfo);
00102 
00103 ZOOM_API(int)
00104 ZOOM_connection_error_x (ZOOM_connection c, const char **cp,
00105                          const char **addinfo, const char **diagset);
00106 
00107 /* returns error code */
00108 ZOOM_API(int)
00109 ZOOM_connection_errcode (ZOOM_connection c);
00110 /* returns error message */
00111 ZOOM_API(const char *)
00112 ZOOM_connection_errmsg (ZOOM_connection c);
00113 /* returns additional info */
00114 ZOOM_API(const char *)
00115 ZOOM_connection_addinfo (ZOOM_connection c);
00116 /* returns diagnostic set */
00117 ZOOM_API(const char *)
00118 ZOOM_connection_diagset (ZOOM_connection c);
00119 /* translates error code into human-readable string */
00120 ZOOM_API(const char *)
00121 ZOOM_diag_str (int error);
00122 
00123 #define ZOOM_ERROR_NONE 0
00124 #define ZOOM_ERROR_CONNECT 10000
00125 #define ZOOM_ERROR_MEMORY  10001
00126 #define ZOOM_ERROR_ENCODE  10002
00127 #define ZOOM_ERROR_DECODE  10003
00128 #define ZOOM_ERROR_CONNECTION_LOST 10004
00129 #define ZOOM_ERROR_INIT 10005
00130 #define ZOOM_ERROR_INTERNAL 10006
00131 #define ZOOM_ERROR_TIMEOUT 10007
00132 #define ZOOM_ERROR_UNSUPPORTED_PROTOCOL 10008
00133 #define ZOOM_ERROR_UNSUPPORTED_QUERY 10009
00134 #define ZOOM_ERROR_INVALID_QUERY 10010
00135 #define ZOOM_ERROR_CQL_PARSE 10011
00136 #define ZOOM_ERROR_CQL_TRANSFORM 10012
00137 #define ZOOM_ERROR_CCL_CONFIG 10013
00138 #define ZOOM_ERROR_CCL_PARSE 10014
00139 
00140 ZOOM_API(int)
00141 ZOOM_connection_last_event(ZOOM_connection cs);
00142 
00143 #define ZOOM_EVENT_NONE 0
00144 #define ZOOM_EVENT_CONNECT 1
00145 #define ZOOM_EVENT_SEND_DATA  2
00146 #define ZOOM_EVENT_RECV_DATA 3
00147 #define ZOOM_EVENT_TIMEOUT 4
00148 #define ZOOM_EVENT_UNKNOWN 5
00149 #define ZOOM_EVENT_SEND_APDU 6
00150 #define ZOOM_EVENT_RECV_APDU 7
00151 #define ZOOM_EVENT_RECV_RECORD 8
00152 #define ZOOM_EVENT_RECV_SEARCH 9
00153 #define ZOOM_EVENT_END 10
00154 
00155 /* ----------------------------------------------------------- */
00156 /* result sets */
00157 
00158 /* create result set given a search */
00159 ZOOM_API(ZOOM_resultset)
00160 ZOOM_connection_search(ZOOM_connection, ZOOM_query q);
00161 /* create result set given PQF query */
00162 ZOOM_API(ZOOM_resultset)
00163 ZOOM_connection_search_pqf(ZOOM_connection c, const char *q);
00164 
00165 /* destroy result set */
00166 ZOOM_API(void)
00167 ZOOM_resultset_destroy(ZOOM_resultset r);
00168 
00169 /* result set option */
00170 ZOOM_API(const char *)
00171 ZOOM_resultset_option_get (ZOOM_resultset r, const char *key);
00172 ZOOM_API(void)
00173 ZOOM_resultset_option_set (ZOOM_resultset r, const char *key, const char *val);
00174 
00175 /* return size of result set (alias hit count AKA result count) */
00176 ZOOM_API(size_t)
00177 ZOOM_resultset_size (ZOOM_resultset r);
00178 
00179 /* retrieve records */
00180 ZOOM_API(void)
00181 ZOOM_resultset_records (ZOOM_resultset r, ZOOM_record *recs,
00182                         size_t start, size_t count);
00183 
00184 /* return record object at pos. Returns 0 if unavailable */
00185 ZOOM_API(ZOOM_record)
00186 ZOOM_resultset_record (ZOOM_resultset s, size_t pos);
00187 
00188 /* like ZOOM_resultset_record - but never blocks .. */
00189 ZOOM_API(ZOOM_record)
00190 ZOOM_resultset_record_immediate (ZOOM_resultset s, size_t pos);
00191 
00192 /* reset record cache for result set */
00193 ZOOM_API(void)
00194 ZOOM_resultset_cache_reset(ZOOM_resultset r);
00195 
00196 /* ----------------------------------------------------------- */
00197 /* records */
00198 
00199 /* get record information, in a form given by type */
00200 ZOOM_API(const char *)
00201 ZOOM_record_get (ZOOM_record rec, const char *type, int *len);
00202 
00203 /* destroy record */
00204 ZOOM_API(void)
00205 ZOOM_record_destroy (ZOOM_record rec);
00206 
00207 /* return copy of record */
00208 ZOOM_API(ZOOM_record)
00209 ZOOM_record_clone (ZOOM_record srec);
00210 
00211 /* return error info (surrogate diagnostic) for record */
00212 ZOOM_API(int)
00213     ZOOM_record_error(ZOOM_record rec, const char **msg,
00214                       const char **addinfo, const char **diagset);
00215     
00216 /* ----------------------------------------------------------- */
00217 /* queries */
00218 
00219 /* create search object */
00220 ZOOM_API(ZOOM_query)
00221 ZOOM_query_create(void);
00222 /* destroy it */
00223 ZOOM_API(void)
00224 ZOOM_query_destroy(ZOOM_query s);
00225 /* CQL */
00226 ZOOM_API(int)
00227 ZOOM_query_cql(ZOOM_query s, const char *str);
00228 /* CQL translated client-side into RPN: `conn' is optional for diagnostics */
00229 ZOOM_API(int)
00230 ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn);
00231 /* CCL translated client-side into RPN: `conn' is optional for diagnostics */
00232 ZOOM_API(int)
00233 ZOOM_query_ccl2rpn(ZOOM_query s, const char *query_str,
00234                    const char *config, 
00235                    int *ccl_error, const char **error_string, int *error_pos);
00236 /* PQF */
00237 ZOOM_API(int)
00238 ZOOM_query_prefix(ZOOM_query s, const char *str);
00239 /* specify sort criteria for search */
00240 ZOOM_API(int)
00241 ZOOM_query_sortby(ZOOM_query s, const char *criteria);
00242 
00243 /* ----------------------------------------------------------- */
00244 /* scan */
00245 ZOOM_API(ZOOM_scanset)
00246 ZOOM_connection_scan (ZOOM_connection c, const char *startterm);
00247 
00248 ZOOM_API(ZOOM_scanset)
00249 ZOOM_connection_scan1 (ZOOM_connection c, ZOOM_query startterm);
00250 
00251 ZOOM_API(const char *)
00252 ZOOM_scanset_term(ZOOM_scanset scan, size_t pos,
00253                   int *occ, int *len);
00254 
00255 ZOOM_API(const char *)
00256 ZOOM_scanset_display_term(ZOOM_scanset scan, size_t pos,
00257                           int *occ, int *len);
00258 
00259 ZOOM_API(size_t)
00260 ZOOM_scanset_size(ZOOM_scanset scan);
00261 
00262 ZOOM_API(void)
00263 ZOOM_scanset_destroy (ZOOM_scanset scan);
00264 
00265 ZOOM_API(const char *)
00266     ZOOM_scanset_option_get (ZOOM_scanset scan, const char *key);
00267 
00268 ZOOM_API(void)
00269     ZOOM_scanset_option_set (ZOOM_scanset scan, const char *key,
00270                              const char *val);
00271 /* ----------------------------------------------------------- */
00272 /* Extended Services Packages */
00273 
00274 ZOOM_API(ZOOM_package)
00275     ZOOM_connection_package (ZOOM_connection c, ZOOM_options options);
00276 
00277 ZOOM_API(void)
00278     ZOOM_package_destroy(ZOOM_package p);
00279 
00280 ZOOM_API(void)
00281     ZOOM_package_send (ZOOM_package p, const char *type);
00282 
00283 ZOOM_API(const char *)
00284     ZOOM_package_option_get (ZOOM_package p, const char *key);
00285 
00286 ZOOM_API(const char *)
00287     ZOOM_package_option_getl (ZOOM_package p, const char *key, int *lenp);
00288 
00289 ZOOM_API(void)
00290     ZOOM_package_option_set (ZOOM_package p, const char *key,
00291                              const char *val);
00292 
00293 ZOOM_API(void)
00294     ZOOM_package_option_setl (ZOOM_package p, const char *key,
00295                               const char *val, int len);
00296 
00297 /* ----------------------------------------------------------- */
00298 /* Sort.  First function is deprecated, use second instead */
00299 ZOOM_API(void)
00300     ZOOM_resultset_sort(ZOOM_resultset r,
00301                         const char *sort_type, const char *sort_spec);
00302 ZOOM_API(int)
00303     ZOOM_resultset_sort1(ZOOM_resultset r,
00304                         const char *sort_type, const char *sort_spec);
00305 
00306 /* ----------------------------------------------------------- */
00307 /* options */
00308 
00309 ZOOM_API(ZOOM_options_callback)
00310     ZOOM_options_set_callback (ZOOM_options opt,
00311                                ZOOM_options_callback c,
00312                                void *handle);
00313 ZOOM_API(ZOOM_options)
00314 ZOOM_options_create (void);
00315 
00316 ZOOM_API(ZOOM_options)
00317 ZOOM_options_create_with_parent (ZOOM_options parent);
00318 
00319 ZOOM_API(ZOOM_options)
00320     ZOOM_options_create_with_parent2 (ZOOM_options parent1,
00321                                       ZOOM_options parent2);
00322 
00323 ZOOM_API(ZOOM_options)
00324     ZOOM_options_dup(ZOOM_options src);
00325 
00326 ZOOM_API(const char *)
00327 ZOOM_options_get (ZOOM_options opt, const char *name);
00328 
00329 ZOOM_API(const char *)
00330 ZOOM_options_getl (ZOOM_options opt, const char *name, int *lenp);
00331 
00332 ZOOM_API(void)
00333 ZOOM_options_set (ZOOM_options opt, const char *name, const char *v);
00334 
00335 ZOOM_API(void)
00336 ZOOM_options_setl (ZOOM_options opt, const char *name, const char *value,
00337                    int len);
00338 
00339 ZOOM_API(void)
00340 ZOOM_options_destroy (ZOOM_options opt);
00341 
00342 ZOOM_API(int)
00343 ZOOM_options_get_bool (ZOOM_options opt, const char *name, int defa);
00344 
00345 ZOOM_API(int)
00346 ZOOM_options_get_int (ZOOM_options opt, const char *name, int defa);
00347 
00348 ZOOM_API(void)
00349 ZOOM_options_set_int(ZOOM_options opt, const char *name, int value);
00350 
00352 #define ZOOM_SELECT_READ 1
00353 
00354 #define ZOOM_SELECT_WRITE 2
00355 
00356 #define ZOOM_SELECT_EXCEPT 4
00357 
00369 ZOOM_API(int)
00370 ZOOM_event (int no, ZOOM_connection *cs);
00371 
00372 
00378 ZOOM_API(int)
00379 ZOOM_connection_is_idle(ZOOM_connection c);
00380 
00381 
00395 ZOOM_API(int)
00396     ZOOM_event_nonblock(int no, ZOOM_connection *cs);
00397 
00398 
00412 ZOOM_API(int)
00413     ZOOM_connection_process(ZOOM_connection c);
00414 
00415 
00424 ZOOM_API(int)
00425     ZOOM_connection_get_socket(ZOOM_connection c);
00426 
00427 
00435 ZOOM_API(int)
00436     ZOOM_connection_get_mask(ZOOM_connection c);
00437 
00438 
00440 ZOOM_API(int)
00441     ZOOM_connection_set_mask(ZOOM_connection c, int mask);
00442 
00443 
00451 ZOOM_API(int)
00452     ZOOM_connection_get_timeout(ZOOM_connection c);
00453 
00454 
00463 ZOOM_API(int)
00464     ZOOM_connection_fire_event_timeout(ZOOM_connection c);
00465 
00466 
00473 ZOOM_API(int)
00474     ZOOM_connection_fire_event_socket(ZOOM_connection c, int mask);
00475 
00476 
00477 
00486 ZOOM_API(int)
00487     ZOOM_connection_peek_event(ZOOM_connection c);
00488 
00489 ZOOM_API(const char *)
00490     ZOOM_get_event_str(int event);
00491 
00492 ZOOM_END_CDECL
00493 
00494 /*
00495  * Local variables:
00496  * c-basic-offset: 4
00497  * indent-tabs-mode: nil
00498  * End:
00499  * vim: shiftwidth=4 tabstop=8 expandtab
00500  */
00501