modules/access/http/conn.h

   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
  33 struct vlc_http_conn_cbs
  34 {
  35     struct vlc_http_stream *(*stream_open)(struct vlc_http_conn *,
  36                                            const struct vlc_http_msg *);
  37     void (*release)(struct vlc_http_conn *);
  38 };
  39
  40 struct vlc_http_conn
  41 {
  42     const struct vlc_http_conn_cbs *cbs;
  43     struct vlc_tls *tls;
  44 };
  45
  46 static inline struct vlc_http_stream *
  47 vlc_http_stream_open(struct vlc_http_conn *conn, const struct vlc_http_msg *m)
  48 {
  49     return conn->cbs->stream_open(conn, m);
  50 }
  51
  52 static inline void vlc_http_conn_release(struct vlc_http_conn *conn)
  53 {
  54     conn->cbs->release(conn);
  55 }
  56
  57 void vlc_http_err(void *, const char *msg, ...) VLC_FORMAT(2, 3);
  58 void vlc_http_dbg(void *, const char *msg, ...) VLC_FORMAT(2, 3);
  59
  60 /**
  61  * \defgroup http1 HTTP/1.x
  62  * @{
  63  */
  64 struct vlc_http_conn *vlc_h1_conn_create(void *ctx, struct vlc_tls *,
  65                                          bool proxy);
  66 struct vlc_http_stream *vlc_chunked_open(struct vlc_http_stream *,
  67                                          struct vlc_tls *);
  68
  69 /**
  70  * Sends an HTTP/1.x request through a new connection.
  71  *
  72  * This function resolves a the specified HTTP server hostname, establishes a
  73  * connection to specified TCP port of the server, then sends an HTTP request.
  74  * The connection is not protected with TLS.
  75  *
  76  * All those operations are combined in a single function call in order to
  77  * support TCP Fast Open. That can save one round-trip when establishing a new
  78  * HTTP connection.
  79
  80  * \note In the case of TLS, TCP Fast Open would convey the TLS Client Hello
  81  * message rather than the HTTP request header. The HTTP request header can
  82  * however be sent with the TLS False Start. This is handled by the TLS stack
  83  * and does not require a combined function call.
  84  *
  85  * \param ctx opaque context pointer for the HTTP connection
  86  * \param hostname HTTP server or proxy hostname to connect to
  87  * \param port TCP port number to connect to
  88  * \param proxy true of the hostname and port correspond to an HTTP proxy,
  89  *              or false if they correspond to an HTTP origin server
  90  * \param req HTTP request message
  91  * \param idempotent whether the HTTP request is idempotent (e.g. GET),
  92  *                   or not (e.g. POST)
  93  * \param connp pointer to storage space for the established HTTP connection
  94  *              (or NULL if the connection is not to be reused) [OUT]
  95  *              can be NULL if the connection is not meant to be reused
  96  * \return an HTTP stream on success, NULL on error
  97  * \note *connp is undefined on error.
  98  */
  99 struct vlc_http_stream *vlc_h1_request(void *ctx, const char *hostname,
 100                                        unsigned port, bool proxy,
 101                                        const struct vlc_http_msg *req,
 102                                        bool idempotent,
 103                                        struct vlc_http_conn **restrict connp);
 104
 105 /** @} */
 106
 107 /**
 108  * \defgroup h2 HTTP/2.0
 109  * @{
 110  */
 111 struct vlc_http_conn *vlc_h2_conn_create(void *ctx, struct vlc_tls *);
 112
 113 /** @} */
 114
 115 /** @} */