1 /* HTTP source element for use in tests
2  *
3  * Copyright (c) <2015> YouView TV Ltd
4  *
5  * This library is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU Library General Public
7  * License as published by the Free Software Foundation; either
8  * version 2 of the License, or (at your option) any later version.
9  *
10  * This library is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13  * Library General Public License for more details.
14  *
15  * You should have received a copy of the GNU Library General Public
16  * License along with this library; if not, write to the
17  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
18  * Boston, MA 02110-1301, USA.
19  */
20 
21 #ifndef __GST_TEST_HTTP_SRC_H__
22 #define __GST_TEST_HTTP_SRC_H__
23 
24 #include <gst/gst.h>
25 
26 G_BEGIN_DECLS
27 
28 #define GST_TYPE_TEST_HTTP_SRC            (gst_test_http_src_get_type ())
29 
30 /**
31  * TEST_HTTP_SRC_REQUEST_HEADERS_NAME:
32  * The name of the #GstStructure that will contain all the HTTP request
33  * headers
34  */
35 #define TEST_HTTP_SRC_REQUEST_HEADERS_NAME "request-headers"
36 
37 /**
38  * TEST_HTTP_SRC_RESPONSE_HEADERS_NAME:
39  * The name of the #GstStructure that will contain all the HTTP response
40  * headers
41  */
42 #define TEST_HTTP_SRC_RESPONSE_HEADERS_NAME "response-headers"
43 
44 /* structure used by src_start function to configure the
45  * GstTestHTTPSrc plugin.
46  * It specifies information about a given URI.
47  */
48 typedef struct _GstTestHTTPSrcInput
49 {
50   gpointer context; /* opaque pointer that can be used in callbacks */
51   guint64 size; /* size of resource, in bytes */
52   GstStructure *request_headers;
53   GstStructure *response_headers;
54   guint status_code; /* HTTP status code */
55 } GstTestHTTPSrcInput;
56 
57 /* Opaque structure used by GstTestHTTPSrc */
58 typedef struct _GstTestHTTPSrc GstTestHTTPSrc;
59 
60 typedef struct _GstTestHTTPSrcCallbacks {
61   /**
62    * src_start:
63    * @src: The #GstTestHTTPSrc calling this callback
64    * @uri: The URI that is being requested
65    * @input_data: (out) The implementation of this callback is
66    * responsible for filling in this #GstTestHTTPSrcInput
67    * with the appropriate information, return returning %TRUE.
68    * If returning %FALSE, only GstTestHTTPSrcInput::status_code
69    * should be updated.
70    * Returns: %TRUE if GstTestHTTPSrc should respond to this URI,
71    * using the supplied input_data.
72    *
73    * src_start is used to "open" the given URI. The callback must return
74    * %TRUE to simulate a success, and set appropriate fields in input_data.
75    * Returning %FALSE indicates that the request URI is not found.
76    * In this situation GstTestHTTPSrc will cause the appropriate
77    * 404 error to be posted to the bus
78    */
79   gboolean (*src_start)(GstTestHTTPSrc *src,
80                         const gchar *uri,
81                         GstTestHTTPSrcInput *input_data,
82                         gpointer user_data);
83   /**
84    * src_create:
85    * @src: the #GstTestHTTPSrc calling this callback
86    * @offset: the offset from the start of the resource
87    * @length: requested number of bytes
88    * @retbuf: (out) used to return a newly allocated #GstBuffer
89    * @context: (allow none) the value of the context field
90    * in #GstTestHTTPSrcInput.
91    * @user_data: the value of user_data provided to
92    * #gst_test_http_src_install_callbacks
93    * Returns: %GST_FLOW_OK to indicate success, or some other value of
94    * #GstFlowReturn to indicate EOS or error.
95    *
96    * The src_create function is used to create a #GstBuffer for
97    * simulating the data that is returned when accessing this
98    * "open" stream. It can also be used to simulate various error
99    * conditions by returning something other than %GST_FLOW_OK
100    */
101   GstFlowReturn (*src_create)(GstTestHTTPSrc *src,
102                               guint64 offset,
103                               guint length,
104                               GstBuffer ** retbuf,
105                               gpointer context,
106                               gpointer user_data);
107 } GstTestHTTPSrcCallbacks;
108 
109 GType gst_test_http_src_get_type (void);
110 
111 /**
112  * gst_test_http_src_register_plugin:
113  * @registry: the #GstRegistry to use for registering this plugin
114  * @name: the name to use for this plugin
115  * Returns: true if successful
116  *
117  * Registers this plugin with the GstRegitry using the given name. It will
118  * be given a high rank, so that it will be picked in preference to any
119  * other element that implements #GstURIHandler.
120  */
121 gboolean gst_test_http_src_register_plugin (GstRegistry * registry, const gchar * name);
122 
123 /**
124  * gst_test_http_src_install_callbacks:
125  * @callbacks: the #GstTestHTTPSrcCallbacks callback functions that will
126  * be called every time this element is asked to open a URI or provide data
127  * for an open URI.
128  * @user_data: a pointer that is passed to every callback
129  */
130 void gst_test_http_src_install_callbacks (const GstTestHTTPSrcCallbacks *callbacks, gpointer user_data);
131 
132 /**
133  * gst_test_http_src_set_default_blocksize:
134  * @blocksize: the default block size to use (0=use #GstBaseSrc default)
135  *
136  * Set the default blocksize that will be used by instances of
137  * #GstTestHTTPSrc. It specifies the size (in bytes) that will be
138  * returned in each #GstBuffer. This default can be overridden
139  * by an instance of #GstTestHTTPSrc using the "blocksize" property
140  * of #GstBaseSrc
141  */
142 void gst_test_http_src_set_default_blocksize (guint blocksize);
143 
144 G_END_DECLS
145 
146 #endif /* __GST_TEST_HTTP_SRC_H__ */
147