OpenShot Audio Library | OpenShotAudio 0.4.0
|
#include <juce_URL.h>
Classes | |
class | DownloadTask |
struct | DownloadTaskListener |
class | DownloadTaskOptions |
class | InputStreamOptions |
Public Types | |
enum class | ParameterHandling { inAddress , inPostData } |
using | OpenStreamProgressCallback = bool(void *context, int bytesSent, int totalBytes) |
Public Member Functions | |
URL () | |
URL (const String &url) | |
URL (File localFile) | |
bool | operator== (const URL &) const |
bool | operator!= (const URL &) const |
String | toString (bool includeGetParameters) const |
bool | isEmpty () const noexcept |
bool | isWellFormed () const |
String | getDomain () const |
String | getSubPath (bool includeGetParameters=false) const |
String | getQueryString () const |
String | getAnchorString () const |
String | getScheme () const |
bool | isLocalFile () const |
File | getLocalFile () const |
String | getFileName () const |
int | getPort () const |
URL | withNewDomainAndPath (const String &newFullPath) const |
URL | withNewSubPath (const String &newPath) const |
URL | getParentURL () const |
URL | getChildURL (const String &subPath) const |
URL | withParameter (const String ¶meterName, const String ¶meterValue) const |
URL | withParameters (const StringPairArray ¶metersToAdd) const |
URL | withAnchor (const String &anchor) const |
URL | withFileToUpload (const String ¶meterName, const File &fileToUpload, const String &mimeType) const |
URL | withDataToUpload (const String ¶meterName, const String &filename, const MemoryBlock &fileContentToUpload, const String &mimeType) const |
const StringArray & | getParameterNames () const noexcept |
const StringArray & | getParameterValues () const noexcept |
URL | withPOSTData (const String &postData) const |
URL | withPOSTData (const MemoryBlock &postData) const |
String | getPostData () const |
const MemoryBlock & | getPostDataAsMemoryBlock () const noexcept |
bool | launchInDefaultBrowser () const |
std::unique_ptr< InputStream > | createInputStream (const InputStreamOptions &options) const |
std::unique_ptr< OutputStream > | createOutputStream () const |
std::unique_ptr< DownloadTask > | downloadToFile (const File &targetLocation, String extraHeaders=String(), DownloadTaskListener *listener=nullptr, bool usePostCommand=false) |
std::unique_ptr< DownloadTask > | downloadToFile (const File &targetLocation, const DownloadTaskOptions &options) |
bool | readEntireBinaryStream (MemoryBlock &destData, bool usePostCommand=false) const |
String | readEntireTextStream (bool usePostCommand=false) const |
std::unique_ptr< XmlElement > | readEntireXmlStream (bool usePostCommand=false) const |
std::unique_ptr< InputStream > | createInputStream (bool doPostLikeRequest, OpenStreamProgressCallback *progressCallback=nullptr, void *progressCallbackContext=nullptr, String extraHeaders={}, int connectionTimeOutMs=0, StringPairArray *responseHeaders=nullptr, int *statusCode=nullptr, int numRedirectsToFollow=5, String httpRequestCmd={}) const |
Static Public Member Functions | |
static bool | isProbablyAWebsiteURL (const String &possibleURL) |
static bool | isProbablyAnEmailAddress (const String &possibleEmailAddress) |
static String | addEscapeChars (const String &stringToAddEscapeCharsTo, bool isParameter, bool roundBracketsAreLegal=true) |
static String | removeEscapeChars (const String &stringToRemoveEscapeCharsFrom) |
static URL | createWithoutParsing (const String &url) |
Represents a URL and has a bunch of useful functions to manipulate it.
This class can be used to launch URLs in browsers, and also to create InputStreams that can read from remote HTTP or FTP sources.
Definition at line 37 of file juce_URL.h.
using juce::URL::OpenStreamProgressCallback = bool (void* context, int bytesSent, int totalBytes) |
Definition at line 669 of file juce_URL.h.
|
strong |
Definition at line 310 of file juce_URL.h.
juce::URL::URL | ( | ) |
Creates an empty URL.
Definition at line 138 of file juce_URL.cpp.
Referenced by createWithoutParsing().
juce::URL::URL | ( | const String & | url | ) |
Creates a URL from a string.
This will parse any embedded parameters after a '?' character and store them in the list (see getParameterNames etc). If you don't want this to happen, you can use createWithoutParsing().
Definition at line 140 of file juce_URL.cpp.
|
explicit |
Creates URL referring to a local file on your disk using the file:// scheme.
Definition at line 145 of file juce_URL.cpp.
|
static |
Adds escape sequences to a string to encode any characters that aren't legal in a URL.
E.g. any spaces will be replaced with "%20".
This is the opposite of removeEscapeChars().
stringToAddEscapeCharsTo | the string to escape. |
isParameter | if true then the string is going to be used as a parameter, so it also encodes '$' and ',' (which would otherwise be legal in a URL. |
roundBracketsAreLegal | technically round brackets are ok in URLs, however, some servers (like AWS) also want round brackets to be escaped. |
Definition at line 966 of file juce_URL.cpp.
Referenced by getAnchorString(), and URL().
std::unique_ptr< InputStream > juce::URL::createInputStream | ( | bool | doPostLikeRequest, |
OpenStreamProgressCallback * | progressCallback = nullptr , |
||
void * | progressCallbackContext = nullptr , |
||
String | extraHeaders = {} , |
||
int | connectionTimeOutMs = 0 , |
||
StringPairArray * | responseHeaders = nullptr , |
||
int * | statusCode = nullptr , |
||
int | numRedirectsToFollow = 5 , |
||
String | httpRequestCmd = {} |
||
) | const |
This method has been deprecated.
Definition at line 1004 of file juce_URL.cpp.
std::unique_ptr< InputStream > juce::URL::createInputStream | ( | const InputStreamOptions & | options | ) | const |
Attempts to open a stream that can read from this URL.
Note that this method will block until the first byte of data has been received or an error has occurred.
Note that on some platforms (Android, for example) it's not permitted to do any network action from the message thread, so you must only call it from a background thread.
Unless the URL represents a local file, this method returns an instance of a WebInputStream. You can use dynamic_cast to cast the return value to a WebInputStream which allows you more fine-grained control of the transfer process.
If the URL represents a local file, then this method simply returns a FileInputStream.
options | a set of options that will be used when opening the stream. |
Definition at line 735 of file juce_URL.cpp.
Referenced by juce::URLInputSource::createInputStream(), createInputStream(), juce::URLInputSource::createInputStreamFor(), readEntireBinaryStream(), and readEntireTextStream().
std::unique_ptr< OutputStream > juce::URL::createOutputStream | ( | ) | const |
Attempts to open an output stream to a URL for writing
This method can only be used for certain scheme types such as local files and content:// URIs on Android.
Definition at line 812 of file juce_URL.cpp.
Returns a URL without attempting to remove any embedded parameters from the string.
This may be necessary if you need to create a request that involves both POST parameters and parameters which are embedded in the URL address itself.
Definition at line 219 of file juce_URL.cpp.
std::unique_ptr< DownloadTask > juce::URL::downloadToFile | ( | const File & | targetLocation, |
const DownloadTaskOptions & | options | ||
) |
Download the URL to a file.
This method attempts to download the URL to a given file location.
Using this method to download files on mobile is less flexible but more reliable than using createInputStream or WebInputStreams as it will attempt to download the file using a native OS background network task. Such tasks automatically deal with network re-connections and continuing your download while your app is suspended.
std::unique_ptr< URL::DownloadTask > juce::URL::downloadToFile | ( | const File & | targetLocation, |
String | extraHeaders = String() , |
||
DownloadTaskListener * | listener = nullptr , |
||
bool | usePostCommand = false |
||
) |
This function is replaced by a new overload accepting a DownloadTaskOptions argument.
Definition at line 1029 of file juce_URL.cpp.
Referenced by downloadToFile().
String juce::URL::getAnchorString | ( | ) | const |
If any anchor is set, returns URL-encoded anchor, including the "#" prefix.
Definition at line 368 of file juce_URL.cpp.
Referenced by getQueryString().
Returns a new URL that refers to a sub-path relative to this one.
e.g. if the URL is "http://www.xyz.com/foo" and you call this with "bar", it'll return "http://www.xyz.com/foo/bar".
Note that there's no way for this method to know whether the original URL is a file or directory, so it's up to you to make sure it's a directory. It also won't attempt to be smart about the content of the childPath string, so if this string is an absolute URL, it'll still just get bolted onto the end of the path.
Definition at line 466 of file juce_URL.cpp.
Referenced by juce::URLInputSource::createInputStreamFor().
String juce::URL::getDomain | ( | ) | const |
Returns just the domain part of the URL.
e.g. for "http://www.xyz.com/foobar", this will return "www.xyz.com".
Definition at line 338 of file juce_URL.cpp.
String juce::URL::getFileName | ( | ) | const |
Returns the file name.
For all but Android's content:// scheme, it will simply return the last segment of the URL, e.g. for "http://www.xyz.com/foo/bar.txt", this will return "bar.txt".
For Android's content:// scheme, it will attempt to resolve the filename located under the URL.
Definition at line 392 of file juce_URL.cpp.
File juce::URL::getLocalFile | ( | ) | const |
Returns the file path of the local file to which this URL refers to.
If the URL does not represent a local file URL (i.e. the URL's scheme is not 'file') then this method will assert.
This method also supports converting Android's content:// URLs to local file paths.
Definition at line 387 of file juce_URL.cpp.
Referenced by createInputStream(), createOutputStream(), readEntireBinaryStream(), and readEntireTextStream().
|
inlinenoexcept |
Returns an array of the names of all the URL's parameters.
e.g. for the url "www.fish.com?type=haddock&amount=some+fish", this array would contain two items: "type" and "amount".
You can call getParameterValues() to get the corresponding value of each parameter. Note that the list can contain multiple parameters with the same name.
Definition at line 249 of file juce_URL.h.
|
inlinenoexcept |
Returns an array of the values of all the URL's parameters.
e.g. for the url "www.fish.com?type=haddock&amount=some+fish", this array would contain two items: "haddock" and "some fish".
The values returned will have been cleaned up to remove any escape characters.
You can call getParameterNames() to get the corresponding name of each parameter. Note that the list can contain multiple parameters with the same name.
Definition at line 263 of file juce_URL.h.
URL juce::URL::getParentURL | ( | ) | const |
Attempts to return a URL which is the parent folder containing this URL.
If there isn't a parent, this method will just return a copy of this URL.
Definition at line 459 of file juce_URL.cpp.
int juce::URL::getPort | ( | ) | const |
Attempts to read a port number from the URL.
Definition at line 432 of file juce_URL.cpp.
|
inline |
Returns the data that was set using withPOSTData().
Definition at line 286 of file juce_URL.h.
|
inlinenoexcept |
Returns the data that was set using withPOSTData() as a MemoryBlock.
Definition at line 289 of file juce_URL.h.
String juce::URL::getQueryString | ( | ) | const |
If any parameters are set, returns these URL-encoded, including the "?" prefix.
Definition at line 355 of file juce_URL.cpp.
Referenced by getSubPath(), and toString().
String juce::URL::getScheme | ( | ) | const |
Returns the scheme of the URL.
e.g. for "http://www.xyz.com/foobar", this will return "http" (it won't include the colon).
Definition at line 376 of file juce_URL.cpp.
Referenced by isLocalFile().
String juce::URL::getSubPath | ( | bool | includeGetParameters = false | ) | const |
Returns the path part of the URL.
e.g. for "http://www.xyz.com/foo/bar?x=1", this will return "foo/bar".
includeGetParameters | if this is true and any parameters have been set with the withParameter() method, then the string will have these appended on the end and URL-encoded. |
Definition at line 343 of file juce_URL.cpp.
Referenced by juce::URLInputSource::createInputStreamFor().
|
noexcept |
Returns true if the URL is an empty string.
Definition at line 327 of file juce_URL.cpp.
bool juce::URL::isLocalFile | ( | ) | const |
Returns true if this URL refers to a local file.
Definition at line 382 of file juce_URL.cpp.
Referenced by createInputStream(), createOutputStream(), readEntireBinaryStream(), and readEntireTextStream().
|
static |
Takes a guess as to whether a string might be a valid email address. This isn't foolproof!
Definition at line 553 of file juce_URL.cpp.
|
static |
Takes a guess as to whether a string might be a valid website address. This isn't foolproof!
Definition at line 538 of file juce_URL.cpp.
bool juce::URL::isWellFormed | ( | ) | const |
bool juce::URL::launchInDefaultBrowser | ( | ) | const |
Tries to launch the system's default browser to open the URL.
Definition at line 993 of file juce_URL.cpp.
bool juce::URL::operator!= | ( | const URL & | other | ) | const |
Definition at line 233 of file juce_URL.cpp.
bool juce::URL::operator== | ( | const URL & | other | ) | const |
Compares two URLs.
All aspects of the URLs must be identical for them to match, including any parameters, upload files, etc.
Definition at line 224 of file juce_URL.cpp.
bool juce::URL::readEntireBinaryStream | ( | MemoryBlock & | destData, |
bool | usePostCommand = false |
||
) | const |
Tries to download the entire contents of this URL into a binary data block.
If it succeeds, this will return true and append the data it read onto the end of the memory block.
Note that on some platforms (Android, for example) it's not permitted to do any network action from the message thread, so you must only call it from a background thread.
destData | the memory block to append the new data to. |
usePostCommand | whether to use a POST command to get the data (uses a GET command if this is false). |
Definition at line 833 of file juce_URL.cpp.
String juce::URL::readEntireTextStream | ( | bool | usePostCommand = false | ) | const |
Tries to download the entire contents of this URL as a string.
If it fails, this will return an empty string, otherwise it will return the contents of the downloaded file. If you need to distinguish between a read operation that fails and one that returns an empty string, you'll need to use a different method, such as readEntireBinaryStream().
Note that on some platforms (Android, for example) it's not permitted to do any network action from the message thread, so you must only call it from a background thread.
usePostCommand | whether to use a POST command to get the data (uses a GET command if this is false). |
Definition at line 847 of file juce_URL.cpp.
Referenced by readEntireXmlStream().
std::unique_ptr< XmlElement > juce::URL::readEntireXmlStream | ( | bool | usePostCommand = false | ) | const |
Tries to download the entire contents of this URL and parse it as XML.
If it fails, or if the text that it reads can't be parsed as XML, this will return nullptr.
Note that on some platforms (Android, for example) it's not permitted to do any network action from the message thread, so you must only call it from a background thread.
usePostCommand | whether to use a POST command to get the data (uses a GET command if this is false). |
Definition at line 858 of file juce_URL.cpp.
Replaces any escape character sequences in a string with their original character codes.
E.g. any instances of "%20" will be replaced by a space.
This is the opposite of addEscapeChars().
Definition at line 937 of file juce_URL.cpp.
String juce::URL::toString | ( | bool | includeGetParameters | ) | const |
Returns a string version of the URL.
includeGetParameters | if this is true and any parameters have been set with the withParameter() method, then the string will have these appended on the end and URL-encoded. |
Definition at line 319 of file juce_URL.cpp.
Referenced by getFileName(), juce::URLInputSource::hashCode(), and launchInDefaultBrowser().
Returns a copy of this URL, with an anchor added to the end of the URL.
Definition at line 883 of file juce_URL.cpp.
URL juce::URL::withDataToUpload | ( | const String & | parameterName, |
const String & | filename, | ||
const MemoryBlock & | fileContentToUpload, | ||
const String & | mimeType | ||
) | const |
Returns a copy of this URL, with a file-upload type parameter added to it.
When performing a POST where one of your parameters is a binary file, this lets you specify the file content.
Note that the filename parameter should not be a full path, it's just the last part of the filename.
Definition at line 929 of file juce_URL.cpp.
URL juce::URL::withFileToUpload | ( | const String & | parameterName, |
const File & | fileToUpload, | ||
const String & | mimeType | ||
) | const |
Returns a copy of this URL, with a file-upload type parameter added to it.
When performing a POST where one of your parameters is a binary file, this lets you specify the file.
Note that the filename is stored, but the file itself won't actually be read until this URL is later used to create a network input stream. If you want to upload data from memory, use withDataToUpload().
Definition at line 922 of file juce_URL.cpp.
Returns a new version of this URL with a different domain and path.
e.g. if the URL is "http://www.xyz.com/foo?x=1" and you call this with "abc.com/zzz", it'll return "http://abc.com/zzz?x=1".
Definition at line 439 of file juce_URL.cpp.
Returns a new version of this URL with a different sub-path.
e.g. if the URL is "http://www.xyz.com/foo?x=1" and you call this with "bar", it'll return "http://www.xyz.com/bar?x=1".
Definition at line 446 of file juce_URL.cpp.
Referenced by juce::URLInputSource::createInputStreamFor().
Returns a copy of this URL, with a GET or POST parameter added to the end.
Any control characters in the value will be URL-encoded.
e.g. calling "withParameter ("amount", "some fish") for the url "www.fish.com" would produce a new url whose <tt>toString (true)</tt> method would return "www.fish.com?amount=some+fish".
Definition at line 864 of file juce_URL.cpp.
URL juce::URL::withParameters | ( | const StringPairArray & | parametersToAdd | ) | const |
Returns a copy of this URL, with a set of GET or POST parameters added.
This is a convenience method, equivalent to calling withParameter for each value.
Definition at line 872 of file juce_URL.cpp.
URL juce::URL::withPOSTData | ( | const MemoryBlock & | postData | ) | const |
Returns a copy of this URL, with a block of data to send as the POST data.
If the URL already contains some POST data, this will replace it, rather than being appended to it.
If no HTTP command is set when calling createInputStream() to read from this URL and some data has been set, it will do a POST request.
Definition at line 896 of file juce_URL.cpp.
Returns a copy of this URL, with a block of data to send as the POST data.
If the URL already contains some POST data, this will replace it, rather than being appended to it.
If no HTTP command is set when calling createInputStream() to read from this URL and some data has been set, it will do a POST request.
Definition at line 891 of file juce_URL.cpp.
Referenced by withPOSTData().