OpenShot Library | OpenShotAudio  0.2.2
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 
27 namespace 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 current 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 immediately.
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 /** @}*/
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.