VLC 4.0.0-dev
conn.h
Go to the documentation of this file.
1/*****************************************************************************
2 * conn.h: HTTP connections
3 *****************************************************************************
4 * Copyright (C) 2015 RĂ©mi Denis-Courmont
5 *
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU Lesser General Public License as published by
8 * the Free Software Foundation; either version 2.1 of the License, or
9 * (at your option) any later version.
10 *
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public License
17 * along with this program; if not, write to the Free Software Foundation,
18 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
19 *****************************************************************************/
20
21/**
22 * \defgroup http_conn Connections
23 * HTTP connections
24 * \ingroup http_connmgr
25 * @{
26 */
27
28struct vlc_tls;
29struct vlc_http_conn;
30struct vlc_http_msg;
31struct vlc_http_stream;
32
34{
35 struct vlc_http_stream *(*stream_open)(struct vlc_http_conn *,
36 const struct vlc_http_msg *,
37 bool has_data);
38 void (*release)(struct vlc_http_conn *);
39};
40
42{
43 const struct vlc_http_conn_cbs *cbs;
44 struct vlc_tls *tls;
45};
46
47static inline struct vlc_http_stream *
48vlc_http_stream_open(struct vlc_http_conn *conn, const struct vlc_http_msg *m,
49 bool has_data)
50{
51 return conn->cbs->stream_open(conn, m, has_data);
52}
53
54static inline void vlc_http_conn_release(struct vlc_http_conn *conn)
55{
56 conn->cbs->release(conn);
57}
58
59void vlc_http_err(void *, const char *msg, ...) VLC_FORMAT(2, 3);
60void vlc_http_dbg(void *, const char *msg, ...) VLC_FORMAT(2, 3);
61
62/**
63 * \defgroup http1 HTTP/1.x
64 * @{
65 */
66struct vlc_http_conn *vlc_h1_conn_create(void *ctx, struct vlc_tls *,
67 bool proxy);
69 struct vlc_tls *);
70ssize_t vlc_https_chunked_write(struct vlc_tls *, const void *base, size_t len,
71 bool eos);
72
73/**
74 * Sends an HTTP/1.x request through a new connection.
75 *
76 * This function resolves a the specified HTTP server hostname, establishes a
77 * connection to specified TCP port of the server, then sends an HTTP request.
78 * The connection is not protected with TLS.
79 *
80 * All those operations are combined in a single function call in order to
81 * support TCP Fast Open. That can save one round-trip when establishing a new
82 * HTTP connection.
83
84 * \note In the case of TLS, TCP Fast Open would convey the TLS Client Hello
85 * message rather than the HTTP request header. The HTTP request header can
86 * however be sent with the TLS False Start. This is handled by the TLS stack
87 * and does not require a combined function call.
88 *
89 * \param ctx opaque context pointer for the HTTP connection
90 * \param hostname HTTP server or proxy hostname to connect to
91 * \param port TCP port number to connect to
92 * \param proxy true of the hostname and port correspond to an HTTP proxy,
93 * or false if they correspond to an HTTP origin server
94 * \param req HTTP request message
95 * \param idempotent whether the HTTP request is idempotent (e.g. GET),
96 * or not (e.g. POST)
97 * \param has_data whether the HTTP request will have a request payload
98 * \param connp pointer to storage space for the established HTTP connection
99 * (or NULL if the connection is not to be reused) [OUT]
100 * can be NULL if the connection is not meant to be reused
101 * \return an HTTP stream on success, NULL on error
102 * \note *connp is undefined on error.
103 */
104struct vlc_http_stream *vlc_h1_request(void *ctx, const char *hostname,
105 unsigned port, bool proxy,
106 const struct vlc_http_msg *req,
107 bool idempotent, bool has_data,
108 struct vlc_http_conn **restrict connp);
109
110/** @} */
111
112/**
113 * \defgroup h2 HTTP/2.0
114 * @{
115 */
116struct vlc_http_conn *vlc_h2_conn_create(void *ctx, struct vlc_tls *);
117
118/** @} */
119
120/** @} */
#define VLC_FORMAT(x, y)
String format function annotation.
Definition: vlc_common.h:204
struct vlc_http_conn * vlc_h2_conn_create(void *ctx, struct vlc_tls *)
Definition: h2conn.c:873
struct vlc_http_stream * vlc_chunked_open(struct vlc_http_stream *, struct vlc_tls *)
Definition: chunked.c:180
struct vlc_http_stream * vlc_h1_request(void *ctx, const char *hostname, unsigned port, bool proxy, const struct vlc_http_msg *req, bool idempotent, bool has_data, struct vlc_http_conn **restrict connp)
Sends an HTTP/1.x request through a new connection.
Definition: h1conn.c:366
struct vlc_http_conn * vlc_h1_conn_create(void *ctx, struct vlc_tls *, bool proxy)
Definition: h1conn.c:349
ssize_t vlc_https_chunked_write(struct vlc_tls *, const void *base, size_t len, bool eos)
Definition: chunked.c:39
static void vlc_http_conn_release(struct vlc_http_conn *conn)
Definition: conn.h:54
void vlc_http_err(void *, const char *msg,...) VLC_FORMAT(2
void void vlc_http_dbg(void *, const char *msg,...) VLC_FORMAT(2
static struct vlc_http_stream * vlc_http_stream_open(struct vlc_http_conn *conn, const struct vlc_http_msg *m, bool has_data)
Definition: conn.h:48
Definition: conn.h:34
struct vlc_http_stream *(* stream_open)(struct vlc_http_conn *, const struct vlc_http_msg *, bool has_data)
Definition: conn.h:35
void(* release)(struct vlc_http_conn *)
Definition: conn.h:38
Definition: conn.h:42
struct vlc_tls * tls
Definition: conn.h:44
const struct vlc_http_conn_cbs * cbs
Definition: conn.h:43
Definition: message.c:43
HTTP stream.
Definition: message.h:371
Transport layer socket.
Definition: vlc_tls.h:66