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 
28 struct vlc_tls;
29 struct vlc_http_conn;
30 struct vlc_http_msg;
31 struct 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 
47 static inline struct vlc_http_stream *
48 vlc_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 
54 static inline void vlc_http_conn_release(struct vlc_http_conn *conn)
55 {
56  conn->cbs->release(conn);
57 }
58 
59 void vlc_http_err(void *, const char *msg, ...) VLC_FORMAT(2, 3);
60 void vlc_http_dbg(void *, const char *msg, ...) VLC_FORMAT(2, 3);
61 
62 /**
63  * \defgroup http1 HTTP/1.x
64  * @{
65  */
66 struct vlc_http_conn *vlc_h1_conn_create(void *ctx, struct vlc_tls *,
67  bool proxy);
69  struct vlc_tls *);
70 ssize_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  */
104 struct 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  */
116 struct 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:211
struct vlc_http_conn * vlc_h2_conn_create(void *ctx, struct vlc_tls *)
Definition: h2conn.c:870
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_stream * vlc_chunked_open(struct vlc_http_stream *, struct vlc_tls *)
Definition: chunked.c:180
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:366
Transport layer socket.
Definition: vlc_tls.h:66