← Back to branch summary

~ubuntu-branches/debian/stretch/libxr/stretch

« back to all changes in this revision

Viewing changes to include/xr-client.h

  • Committer: Bazaar Package Importer
  • Author(s): Fabien Boucher
  • Date: 2009-10-14 00:52:51 UTC
  • Revision ID: james.westby@ubuntu.com-20091014005251-epx05xv5ef9188q0
Tags: upstream-1.0
Import upstream version 1.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
include/xr-client.h
 
1
/* 
 
2
 * Copyright 2006-2008 Ondrej Jirman <ondrej.jirman@zonio.net>
 
3
 * 
 
4
 * This file is part of libxr.
 
5
 *
 
6
 * Libxr is free software: you can redistribute it and/or modify it under the
 
7
 * terms of the GNU Lesser General Public License as published by the Free
 
8
 * Software Foundation, either version 2 of the License, or (at your option) any
 
9
 * later version.
 
10
 *
 
11
 * Libxr is distributed in the hope that it will be useful, but WITHOUT ANY
 
12
 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
 
13
 * A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
 
14
 * details.
 
15
 *
 
16
 * You should have received a copy of the GNU Lesser General Public License
 
17
 * along with libxr.  If not, see <http://www.gnu.org/licenses/>.
 
18
 */
 
19
 
 
20
/** @file xr-client.h
 
21
 *
 
22
 * XML-RPC Client Connection API
 
23
 *
 
24
 * This API can be used to implement XML-RPC clients.
 
25
 *
 
26
 * Then basically you just create (@ref xr_client_new) connection object
 
27
 * (@ref xr_client_conn) and open connection to given URI
 
28
 * (@ref xr_client_open). Now you are free to perform XML-RPC calls
 
29
 * using code generated by @ref xdlc.
 
30
 */
 
31
 
 
32
#ifndef __XR_CLIENT_H__
 
33
#define __XR_CLIENT_H__
 
34
 
 
35
#include <openssl/ssl.h>
 
36
#include "xr-call.h"
 
37
#include "xr-http.h"
 
38
#include "xr-value-utils.h"
 
39
 
 
40
#define XR_CLIENT_ERROR xr_client_error_quark()
 
41
 
 
42
typedef enum
 
43
{
 
44
  XR_CLIENT_ERROR_MARCHALIZER,
 
45
  XR_CLIENT_ERROR_CLOSED,
 
46
  XR_CLIENT_ERROR_CONNECT,
 
47
  XR_CLIENT_ERROR_IO,
 
48
  XR_CLIENT_ERROR_FAILED
 
49
} XRClientError;
 
50
 
 
51
G_BEGIN_DECLS
 
52
 
 
53
/** Opaque data structrure that represents client connection.
 
54
 */
 
55
typedef struct _xr_client_conn xr_client_conn;
 
56
 
 
57
/** Create new connection object.
 
58
 *
 
59
 * @param err Error object.
 
60
 *
 
61
 * @return New connection object.
 
62
 */
 
63
xr_client_conn* xr_client_new(GError** err);
 
64
 
 
65
/** Get SSL context used by the client.
 
66
 *
 
67
 * This can be used for custom SSL setup.
 
68
 * 
 
69
 * @param server Server object.
 
70
 * 
 
71
 * @return SSL_CTX pointer owned by the xr_server.
 
72
 */
 
73
SSL_CTX* xr_client_get_ssl_context(xr_client_conn* conn);
 
74
 
 
75
/** Free connection object. This function calls @ref xr_client_close if
 
76
 * necessary.
 
77
 *
 
78
 * @param conn Connection object.
 
79
 */
 
80
void xr_client_free(xr_client_conn* conn);
 
81
 
 
82
/** Set transport type.
 
83
 *
 
84
 * Currently supported types are XR_CALL_XML_RPC and XR_CALL_JSON_RPC (not all
 
85
 * xr_value types).
 
86
 * 
 
87
 * @param conn Connection object.
 
88
 * @param transport Transport type.
 
89
 * 
 
90
 * @return TRUE on success, FALSE if transport is not available.
 
91
 */
 
92
gboolean xr_client_set_transport(xr_client_conn* conn, xr_call_transport transport);
 
93
 
 
94
/** Set HTTP header to be used in RPCs.
 
95
 *
 
96
 * This setting persists until you remove header by passing NULL value or by
 
97
 * calling xr_client_reset_http_headers().
 
98
 * 
 
99
 * @param conn Connection object.
 
100
 * @param name HTTP header name.
 
101
 * @param value HTTP header value. Value is not escaped and thus it should not span
 
102
 *   multiple lines.
 
103
 */
 
104
void xr_client_set_http_header(xr_client_conn* conn, const char* name, const char* value);
 
105
 
 
106
/** Remove all user defined HTTP headers.
 
107
 * 
 
108
 * @param conn Connection object.
 
109
 */
 
110
void xr_client_reset_http_headers(xr_client_conn* conn);
 
111
 
 
112
/** Helper function for setting HTTP headers for Basic Authorization.
 
113
 * 
 
114
 * @param conn Connection object.
 
115
 * @param username Username.
 
116
 * @param password Password.
 
117
 */
 
118
void xr_client_basic_auth(xr_client_conn* conn, const char* username, const char* password);
 
119
 
 
120
/** Get HTTP transport object.
 
121
 * 
 
122
 * @param conn Connection object.
 
123
 * 
 
124
 * @return HTTP transport object.
 
125
 */
 
126
xr_http* xr_client_get_http(xr_client_conn* conn);
 
127
 
 
128
/** Open new connection to the server.
 
129
 *
 
130
 * @param conn Connection object.
 
131
 * @param uri URI of the cleint (http[s]://host[:port]/Servlet).
 
132
 * @param err Error object.
 
133
 *
 
134
 * @return Function returns FALSE on failure and TRUE on success.
 
135
 */
 
136
gboolean xr_client_open(xr_client_conn* conn, const char* uri, GError** err);
 
137
 
 
138
/** Close currently open connection.
 
139
 *
 
140
 * @param conn Connection object.
 
141
 */
 
142
void xr_client_close(xr_client_conn* conn);
 
143
 
 
144
/** Perform XML-RPC call over connection.
 
145
 *
 
146
 * @param conn Connection object.
 
147
 * @param call Call object.
 
148
 * @param err Error object.
 
149
 *
 
150
 * @return Function returns FALSE on failure (including XML-RPC exception) and
 
151
 *   TRUE on success. XML-RPC exception have err->domain == 0.
 
152
 */
 
153
gboolean xr_client_call(xr_client_conn* conn, xr_call* call, GError** err);
 
154
 
 
155
GQuark xr_client_error_quark();
 
156
 
 
157
G_END_DECLS
 
158
 
 
159
#endif