OpenShot Library | libopenshot-audio 0.2.0
juce_WebInputStream.h
1
2/** @weakgroup juce_core-network
3 * @{
4 */
5/*
6 ==============================================================================
7
8 This file is part of the JUCE library.
9 Copyright (c) 2017 - ROLI Ltd.
10
11 JUCE is an open source library subject to commercial or open-source
12 licensing.
13
14 The code included in this file is provided under the terms of the ISC license
15 http://www.isc.org/downloads/software-support-policy/isc-license. Permission
16 To use, copy, modify, and/or distribute this software for any purpose with or
17 without fee is hereby granted provided that the above copyright notice and
18 this permission notice appear in all copies.
19
20 JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
21 EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
22 DISCLAIMED.
23
24 ==============================================================================
25*/
26
27namespace juce
28{
29
30//==============================================================================
31/**
32 An InputStream which can be used to read from a given url.
33
34 @tags{Core}
35*/
37{
38 public:
39 /** Used to receive callbacks for data send progress */
41 {
42 public:
43 virtual ~Listener() = default;
44
45 virtual bool postDataSendProgress (WebInputStream& /*request*/, int /*bytesSent*/, int /*totalBytes*/) { return true; }
46 };
47
48 /** Creates a new WebInputstream which can be used to read from a url.
49
50 @param url The url that should be retrieved. This parameter may also contain
51 post data and/or parameters.
52 @param usePost Specifies whether a GET or a POST command should be used. This
53 parameter will also influence the way parameters are encoded.
54 */
55 WebInputStream (const URL& url, const bool usePost);
56
57 ~WebInputStream() override;
58
59
60 /** Add extra headers to http request
61
62 Returns a reference to itself so that several methods can be chained.
63
64 @param extraHeaders this string is appended onto the headers that are used for
65 the request. It must therefore be a valid set of HTML
66 header directives, separated by newlines.
67 */
68 WebInputStream& withExtraHeaders (const String& extraHeaders);
69
70 /** Override the http command that is sent
71
72 Returns a reference to itself so that several methods can be chained.
73
74 Note that this command will not change the way parameters are sent. This
75 must be specified in the constructor.
76
77 @param customRequestCommand this string is the custom http request command such
78 as POST or GET.
79 */
80 WebInputStream& withCustomRequestCommand (const String& customRequestCommand);
81
82 /** Specify the connection time-out
83
84 Returns a reference to itself so that several methods can be chained.
85
86 @param timeoutInMs the number of milliseconds to wait until the connection
87 request is aborted.
88 */
89 WebInputStream& withConnectionTimeout (int timeoutInMs);
90
91 /** Specify the number of redirects to be followed
92
93 Returns a reference to itself so that several methods can be chained.
94
95 @param numRedirects specifies the number of redirects that will be followed
96 before returning a response (ignored for Android which
97 follows up to 5 redirects)
98 */
99 WebInputStream& withNumRedirectsToFollow (int numRedirects);
100
101 /** Returns a string array pair of the request headers */
102 StringPairArray getRequestHeaders() const;
103
104 /** Returns a string array pair of response headers
105
106 If getResponseHeaders is called without an established connection, then
107 getResponseHeaders will call connect internally and block until connect
108 returns - either due to a successful connection or a connection
109 error.
110
111 @see connect
112 */
113 StringPairArray getResponseHeaders();
114
115 /** Returns the status code returned by the http server
116
117 If getStatusCode is called without an established connection, then
118 getStatusCode will call connect internally and block until connect
119 returns - either due to a successful connection or a connection
120 error.
121
122 @see connect
123 */
124 int getStatusCode();
125
126 /** Wait until the first byte is ready for reading
127
128 This method will attempt to connect to the url given in the constructor
129 and block until the status code and all response headers have been received or
130 an error has occurred.
131
132 Note that most methods will call connect internally if they are called without
133 an established connection. Therefore, it is not necessary to explicitly
134 call connect unless you would like to use a custom listener.
135
136 After a successful call to connect, getResponseHeaders, getTotalLength and
137 getStatusCode will all be non-blocking.
138
139 @param listener A listener to receive progress callbacks on the status
140 of a POST data upload.
141
142 @see getResponseHeaders, getTotalLength, getStatusCode
143 */
144 bool connect (Listener* listener);
145
146 /** Returns true if there was an error during the connection attempt. */
147 bool isError() const;
148
149 /** Will cancel a blocking read and prevent any subsequent connection attempts. */
150 void cancel();
151
152 //==============================================================================
153 /** Returns the total number of bytes available for reading in this stream.
154
155 Note that this is the number of bytes available from the start of the
156 stream, not from the current position.
157
158 If getTotalLength is called without an established connection, then
159 getTotalLength will call connect internally and block until connect
160 returns - either due to a successful connection or a connection
161 error.
162
163 If the size of the stream isn't actually known, this will return -1.
164 */
165 int64 getTotalLength() override;
166
167 /** Reads some data from the stream into a memory buffer.
168
169 This method will block until the bytesToRead bytes are available.
170
171 This method calls connect internally if the connection hasn't already
172 been established.
173
174 @param destBuffer the destination buffer for the data. This must not be null.
175 @param maxBytesToRead the maximum number of bytes to read - make sure the
176 memory block passed in is big enough to contain this
177 many bytes. This value must not be negative.
178
179 @returns the actual number of bytes that were read, which may be less than
180 maxBytesToRead if the stream is exhausted before it gets that far
181 */
182 int read (void* destBuffer, int maxBytesToRead) override;
183
184 /** Returns true if the stream has no more data to read. */
185 bool isExhausted() override;
186
187 /** Returns the offset of the next byte that will be read from the stream.
188 @see setPosition
189 */
190 int64 getPosition() override;
191
192 /** Tries to move the current read position of the stream.
193
194 The position is an absolute number of bytes from the stream's start.
195
196 For a WebInputStream, this method will fail if wantedPos is smaller
197 than the curent position. If wantedPos is greater than the current
198 position, then calling setPosition is the same as calling read, i.e.
199 the skipped data will still be downloaded, although skipped bytes will
200 be discarded immedietely.
201
202 @returns true if the stream manages to reposition itself correctly
203 @see getPosition
204 */
205 bool setPosition (int64 wantedPos) override;
206
207 private:
208 static void createHeadersAndPostData (const URL&, String&, MemoryBlock&);
209 static StringPairArray parseHttpHeaders (const String& headerData);
210
211 class Pimpl;
212 friend class Pimpl;
213
214 Pimpl* const pimpl;
215 bool hasCalledConnect;
216
217 JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (WebInputStream)
218};
219
220} // namespace juce
221
222/** @}*/
Holds a resizable array of primitive or copy-by-value objects.
Definition juce_Array.h:60
The base class for streams that read data.
A class to hold a resizable block of raw data.
A container for holding a set of strings which are keyed by another string.
The JUCE String class!
Definition juce_String.h:43
Represents a URL and has a bunch of useful functions to manipulate it.
Definition juce_URL.h:42
Used to receive callbacks for data send progress.
An InputStream which can be used to read from a given url.
#define JUCE_API
This macro is added to all JUCE public class declarations.