Happy new year
[yaz-moved-to-github.git] / 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