include/yaz/retrieval.h

   1 /* This file is part of the YAZ toolkit.
   2  * Copyright (C) Index Data.
   3  * All rights reserved.
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions are met:
   6  *
   7  *     * Redistributions of source code must retain the above copyright
   8  *       notice, this list of conditions and the following disclaimer.
   9  *     * Redistributions in binary form must reproduce the above copyright
  10  *       notice, this list of conditions and the following disclaimer in the
  11  *       documentation and/or other materials provided with the distribution.
  12  *     * Neither the name of Index Data nor the names of its contributors
  13  *       may be used to endorse or promote products derived from this
  14  *       software without specific prior written permission.
  15  *
  16  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY
  17  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  18  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  19  * DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY
  20  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  21  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  22  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  23  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  25  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26  */
  27
  28 /**
  29  * \file retrieval.h
  30  * \brief Retrieval Utility
  31  */
  32
  33 #ifndef YAZ_RETRIEVAL_H
  34 #define YAZ_RETRIEVAL_H
  35
  36 #include <stddef.h>
  37 #include <yaz/wrbuf.h>
  38 #include <yaz/yconfig.h>
  39 #include <yaz/oid_util.h>
  40 #include <yaz/record_conv.h>
  41
  42 YAZ_BEGIN_CDECL
  43
  44 /** retrieval handle  */
  45 typedef struct yaz_retrieval_struct *yaz_retrieval_t;
  46
  47 /** creates retrieval handle
  48     \return retrieval handle
  49 */
  50 YAZ_EXPORT yaz_retrieval_t yaz_retrieval_create(void);
  51
  52 /** destroys retrieval handle
  53     \param p retrieval handle
  54 */
  55 YAZ_EXPORT void yaz_retrieval_destroy(yaz_retrieval_t p);
  56
  57 #if YAZ_HAVE_XML2
  58 /** configures retrieval
  59     \param p retrieval handle
  60     \param node xmlNode pointer (root element of XML config)
  61     \retval 0 success
  62     \retval -1 failure
  63
  64     On failure, call yaz_retrieval_get_error to get error string.
  65
  66     For retrieval:
  67     \verbatim
  68      <retrievalinfo>
  69        <retrieval syntax="usmarc" name="F"/>
  70        <retrieval syntax="usmarc" name="B"/>
  71        <retrieval syntax="xml" name="marcxml"
  72                   identifier="info:srw/schema/1/marcxml-v1.1">
  73          <backend syntax="usmarc" name="F">
  74            <marc inputformat="marc" outputformat="marcxml"
  75                  inputcharset="marc-8"/>
  76          </backend>
  77        </retrieval>
  78        <retrieval syntax="xml" name="dc">
  79          <backend syntax="usmarc" name="F">
  80            <marc inputformat="marc" outputformat="marcxml"
  81                  inputcharset="marc-8"/>
  82            <xslt stylesheet="MARC21slim2DC.xsl"/>
  83          </backend>
  84        </retrieval>
  85      </retrievalinfo>
  86     \endverbatim
  87 */
  88 YAZ_EXPORT
  89 int yaz_retrieval_configure(yaz_retrieval_t p, const xmlNode *node);
  90
  91
  92 /** configures retrieval with user-defined conversion types
  93     \param p retrieval handle
  94     \param node xmlNode pointer (root element of XML config)
  95     \param types record conversion types
  96     \retval 0 success
  97     \retval -1 failure
  98
  99     On failure, use yaz_retrieval_get_error to get error string.
 100 */
 101 YAZ_EXPORT
 102 int yaz_retrieval_configure_t(yaz_retrieval_t p, const xmlNode *node,
 103                               struct yaz_record_conv_type *types);
 104
 105 #endif
 106
 107 /** performs retrieval request based on schema and format
 108     \param p retrieval handle
 109     \param schema record schema (SRU) / element set name (Z39.50)
 110     \param syntax record syntax (format)
 111     \param match_schema matched schema (if conversion was successful)
 112     \param match_syntax matced syntax OID  if conversion was successful)
 113     \param rc record conversion reference (if conversion was successful)
 114     \param backend_schema backend scchema (if conversion was successful)
 115     \param backend_syntax backend syntax (if conversion was successful)
 116     \retval 0 success, schema and syntax matches
 117     \retval -1 failure, use yaz_retrieval_get_error() for reason
 118     \retval 1 schema does not match
 119     \retval 2 syntax does not match
 120     \retval 3 both match but not together
 121 */
 122 YAZ_EXPORT
 123 int yaz_retrieval_request(yaz_retrieval_t p,
 124                           const char *schema, Odr_oid *syntax,
 125                           const char **match_schema, Odr_oid **match_syntax,
 126                           yaz_record_conv_t *rc,
 127                           const char **backend_schema,
 128                           Odr_oid **backend_syntax);
 129
 130 /** returns error string (for last error)
 131     \param p record conversion handle
 132     \return error string
 133 */
 134 YAZ_EXPORT
 135 const char *yaz_retrieval_get_error(yaz_retrieval_t p);
 136
 137
 138 /** set path for opening stylesheets etc.
 139     \param p record conversion handle
 140     \param path file path (UNIX style with : / Windows with ;)
 141 */
 142 YAZ_EXPORT
 143 void yaz_retrieval_set_path(yaz_retrieval_t p, const char *path);
 144
 145 YAZ_END_CDECL
 146
 147 #endif
 148 /*
 149  * Local variables:
 150  * c-basic-offset: 4
 151  * c-file-style: "Stroustrup"
 152  * indent-tabs-mode: nil
 153  * End:
 154  * vim: shiftwidth=4 tabstop=8 expandtab
 155  */
 156