include/yaz/url.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 url.h
  30  * \brief Fetch URL utility
  31  */
  32
  33 #ifndef YAZ_URL_H
  34 #define YAZ_URL_H
  35
  36 #include <yaz/zgdu.h>
  37
  38 YAZ_BEGIN_CDECL
  39
  40 /** \brief handle for our URL fetcher */
  41 typedef struct yaz_url *yaz_url_t;
  42
  43 /** \brief creates a URL fetcher handle
  44     \returns handle
  45 */
  46 YAZ_EXPORT yaz_url_t yaz_url_create(void);
  47
  48 /** \brief destroys a URL fetcher
  49     \param p handle
  50
  51     Note: OK to pass NULL as p
  52 */
  53 YAZ_EXPORT void yaz_url_destroy(yaz_url_t p);
  54
  55 /** \brief sets proxy for URL fetcher
  56     \param p handle
  57     \param proxy proxy address , e.g "localhost:3128"
  58
  59     Passing a proxy of NULL disables proxy use.
  60 */
  61 YAZ_EXPORT void yaz_url_set_proxy(yaz_url_t p, const char *proxy);
  62
  63 /** \brief sets maximum number of redirects
  64     \param p handle
  65     \param num maximum number of redirects
  66 */
  67 YAZ_EXPORT void yaz_url_set_max_redirects(yaz_url_t p, int num);
  68
  69 /** \brief executes the actual HTTP request (including redirects, etc)
  70     \param p handle
  71     \param uri URL
  72     \param method HTTP method
  73     \param headers HTTP headers to be used (NULL for no custom headers)
  74     \param buf content buffer for HTTP request, NULL for empty content
  75     \param len content length for HTTP request
  76     \returns HTTP response; NULL on ERROR.
  77
  78     Use yaz_url_get_error to get details if NULL is returned.
  79 */
  80 YAZ_EXPORT Z_HTTP_Response *yaz_url_exec(yaz_url_t p, const char *uri,
  81                                          const char *method,
  82                                          Z_HTTP_Header *headers,
  83                                          const char *buf, size_t len);
  84
  85 /** \brief get last error from yaz_url_exec
  86     \param p handle
  87     \returns message (possibly empty string no error occurred)
  88 */
  89 YAZ_EXPORT const char *yaz_url_get_error(yaz_url_t p);
  90
  91 YAZ_END_CDECL
  92
  93 #endif
  94 /*
  95  * Local variables:
  96  * c-basic-offset: 4
  97  * c-file-style: "Stroustrup"
  98  * indent-tabs-mode: nil
  99  * End:
 100  * vim: shiftwidth=4 tabstop=8 expandtab
 101  */
 102