OpenShot Audio Library | OpenShotAudio 0.3.2
Loading...
Searching...
No Matches
juce::URL Class Reference

#include <juce_URL.h>

Classes

class  DownloadTask
 

Public Types

using OpenStreamProgressCallback = bool(void *context, int bytesSent, int totalBytes)
 

Public Member Functions

 URL ()
 
 URL (const String &url)
 
 URL (const URL &)=default
 
URLoperator= (const URL &)=default
 
 URL (URL &&)=default
 
URLoperator= (URL &&)=default
 
 URL (File)
 
 ~URL ()=default
 
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 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 &parameterName, const String &parameterValue) const
 
URL withParameters (const StringPairArray &parametersToAdd) const
 
URL withFileToUpload (const String &parameterName, const File &fileToUpload, const String &mimeType) const
 
URL withDataToUpload (const String &parameterName, const String &filename, const MemoryBlock &fileContentToUpload, const String &mimeType) const
 
const StringArraygetParameterNames () const noexcept
 
const StringArraygetParameterValues () const noexcept
 
URL withPOSTData (const String &postData) const
 
URL withPOSTData (const MemoryBlock &postData) const
 
String getPostData () const
 
const MemoryBlockgetPostDataAsMemoryBlock () const noexcept
 
bool launchInDefaultBrowser () const
 
InputStreamcreateInputStream (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
 
OutputStreamcreateOutputStream () const
 
DownloadTaskdownloadToFile (const File &targetLocation, String extraHeaders=String(), DownloadTask::Listener *listener=nullptr, bool usePostCommand=false)
 
bool readEntireBinaryStream (MemoryBlock &destData, bool usePostCommand=false) const
 
String readEntireTextStream (bool usePostCommand=false) const
 
std::unique_ptr< XmlElementreadEntireXmlStream (bool usePostCommand=false) 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)
 

Detailed Description

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.

Member Typedef Documentation

◆ OpenStreamProgressCallback

This callback function can be used by the createInputStream() method.

It allows your app to receive progress updates during a lengthy POST operation. If you want to continue the operation, this should return true, or false to abort.

Definition at line 299 of file juce_URL.h.

Constructor & Destructor Documentation

◆ URL() [1/3]

juce::URL::URL ( )

Creates an empty URL.

Definition at line 138 of file juce_URL.cpp.

Referenced by createWithoutParsing().

◆ URL() [2/3]

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.

◆ URL() [3/3]

juce::URL::URL ( File  localFile)
explicit

Creates URL referring to a local file on your disk using the file:// scheme.

Definition at line 145 of file juce_URL.cpp.

◆ ~URL()

juce::URL::~URL ( )
default

Destructor.

Member Function Documentation

◆ addEscapeChars()

String juce::URL::addEscapeChars ( const String stringToAddEscapeCharsTo,
bool  isParameter,
bool  roundBracketsAreLegal = true 
)
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().

Parameters
stringToAddEscapeCharsToThe string to escape.
isParameterIf 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.
roundBracketsAreLegalTechnically round brackets are ok in URLs, however, some servers (like AWS) also want round brackets to be escaped.
See also
removeEscapeChars

Definition at line 872 of file juce_URL.cpp.

Referenced by URL().

◆ createInputStream()

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

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.

Parameters
doPostLikeRequestif true, the parameters added to this class will be transferred via the HTTP headers which is typical for POST requests. Otherwise the parameters will be added to the URL address. Additionally, if the parameter httpRequestCmd is not specified (or empty) then this parameter will determine which HTTP request command will be used (POST or GET).
progressCallbackif this is not a nullptr, it lets you supply a callback function to keep track of the operation's progress. This can be useful for lengthy POST operations, so that you can provide user feedback.
progressCallbackContextif a callback is specified, this value will be passed to the function
extraHeadersif not empty, this string is appended onto the headers that are used for the request. It must therefore be a valid set of HTML header directives, separated by newlines.
connectionTimeOutMsif 0, this will use whatever default setting the OS chooses. If a negative number, it will be infinite. Otherwise it specifies a time in milliseconds.
responseHeadersif this is non-null, all the (key, value) pairs received as headers in the response will be stored in this array
statusCodeif this is non-null, it will get set to the http status code, if one is known, or 0 if a code isn't available
numRedirectsToFollowspecifies the number of redirects that will be followed before returning a response (ignored for Android which follows up to 5 redirects)
httpRequestCmdSpecify which HTTP Request to use. If this is empty, then doPostRequest will determine the HTTP request.
Returns
an input stream that the caller must delete, or a null pointer if there was an error trying to open it.

Definition at line 658 of file juce_URL.cpp.

Referenced by readEntireBinaryStream(), and readEntireTextStream().

◆ createOutputStream()

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 727 of file juce_URL.cpp.

◆ createWithoutParsing()

URL juce::URL::createWithoutParsing ( const String url)
static

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 211 of file juce_URL.cpp.

◆ downloadToFile()

DownloadTask * juce::URL::downloadToFile ( const File targetLocation,
String  extraHeaders = String(),
DownloadTask::Listener listener = nullptr,
bool  usePostCommand = false 
)

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.

◆ getChildURL()

URL juce::URL::getChildURL ( const String subPath) const

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.

See also
File::getChildFile

Definition at line 440 of file juce_URL.cpp.

◆ getDomain()

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 330 of file juce_URL.cpp.

◆ getFileName()

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 371 of file juce_URL.cpp.

◆ getLocalFile()

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.

See also
isLocalFile

Definition at line 366 of file juce_URL.cpp.

Referenced by createInputStream(), createOutputStream(), readEntireBinaryStream(), and readEntireTextStream().

◆ getParameterNames()

const StringArray & juce::URL::getParameterNames ( ) const
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.

See also
getParameterValues, withParameter

Definition at line 226 of file juce_URL.h.

◆ getParameterValues()

const StringArray & juce::URL::getParameterValues ( ) const
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.

See also
getParameterNames, withParameter

Definition at line 240 of file juce_URL.h.

◆ getParentURL()

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 433 of file juce_URL.cpp.

◆ getPort()

int juce::URL::getPort ( ) const

Attempts to read a port number from the URL.

Returns
the port number, or 0 if none is explicitly specified.

Definition at line 406 of file juce_URL.cpp.

◆ getPostData()

String juce::URL::getPostData ( ) const
inline

Returns the data that was set using withPOSTData().

Definition at line 271 of file juce_URL.h.

◆ getPostDataAsMemoryBlock()

const MemoryBlock & juce::URL::getPostDataAsMemoryBlock ( ) const
inlinenoexcept

Returns the data that was set using withPOSTData() as MemoryBlock.

Definition at line 274 of file juce_URL.h.

◆ getQueryString()

String juce::URL::getQueryString ( ) const

If any parameters are set, returns these URL encoded, including the "?" prefix.

Definition at line 347 of file juce_URL.cpp.

Referenced by getSubPath(), and toString().

◆ getScheme()

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 355 of file juce_URL.cpp.

Referenced by isLocalFile().

◆ getSubPath()

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".

If includeGetParameters 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 335 of file juce_URL.cpp.

◆ isEmpty()

bool juce::URL::isEmpty ( ) const
noexcept

Returns true if the URL is an empty string.

Definition at line 319 of file juce_URL.cpp.

◆ isLocalFile()

bool juce::URL::isLocalFile ( ) const

Returns true if this URL refers to a local file.

Definition at line 361 of file juce_URL.cpp.

Referenced by createInputStream(), createOutputStream(), readEntireBinaryStream(), and readEntireTextStream().

◆ isProbablyAnEmailAddress()

bool juce::URL::isProbablyAnEmailAddress ( const String possibleEmailAddress)
static

Takes a guess as to whether a string might be a valid email address. This isn't foolproof!

Definition at line 518 of file juce_URL.cpp.

◆ isProbablyAWebsiteURL()

bool juce::URL::isProbablyAWebsiteURL ( const String possibleURL)
static

Takes a guess as to whether a string might be a valid website address. This isn't foolproof!

Definition at line 503 of file juce_URL.cpp.

◆ isWellFormed()

bool juce::URL::isWellFormed ( ) const

True if it seems to be valid.

Definition at line 324 of file juce_URL.cpp.

Referenced by URL().

◆ launchInDefaultBrowser()

bool juce::URL::launchInDefaultBrowser ( ) const

Tries to launch the system's default browser to open the URL. Returns true if this seems to have worked.

Definition at line 899 of file juce_URL.cpp.

◆ operator!=()

bool juce::URL::operator!= ( const URL other) const

Definition at line 225 of file juce_URL.cpp.

◆ operator==()

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 216 of file juce_URL.cpp.

◆ readEntireBinaryStream()

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.

Parameters
destDatathe memory block to append the new data to
usePostCommandwhether to use a POST command to get the data (uses a GET command if this is false)
See also
readEntireTextStream, readEntireXmlStream

Definition at line 747 of file juce_URL.cpp.

◆ readEntireTextStream()

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.

Parameters
usePostCommandwhether to use a POST command to get the data (uses a GET command if this is false)
See also
readEntireBinaryStream, readEntireXmlStream

Definition at line 761 of file juce_URL.cpp.

Referenced by readEntireXmlStream().

◆ 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.

When it returns a valid XmlElement object, the caller is responsible for deleting this object when no longer needed.

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.

Parameters
usePostCommandwhether to use a POST command to get the data (uses a GET command if this is false)
See also
readEntireBinaryStream, readEntireTextStream

Definition at line 772 of file juce_URL.cpp.

◆ removeEscapeChars()

String juce::URL::removeEscapeChars ( const String stringToRemoveEscapeCharsFrom)
static

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().

See also
addEscapeChars

Definition at line 843 of file juce_URL.cpp.

◆ toString()

String juce::URL::toString ( bool  includeGetParameters) const

Returns a string version of the URL.

If includeGetParameters 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 311 of file juce_URL.cpp.

Referenced by getFileName(), and launchInDefaultBrowser().

◆ withDataToUpload()

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.

See also
withFileToUpload

Definition at line 835 of file juce_URL.cpp.

◆ withFileToUpload()

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().

See also
withDataToUpload

Definition at line 828 of file juce_URL.cpp.

◆ withNewDomainAndPath()

URL juce::URL::withNewDomainAndPath ( const String newFullPath) const

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".

See also
withNewSubPath

Definition at line 413 of file juce_URL.cpp.

◆ withNewSubPath()

URL juce::URL::withNewSubPath ( const String newPath) const

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".

See also
withNewDomainAndPath

Definition at line 420 of file juce_URL.cpp.

◆ withParameter()

URL juce::URL::withParameter ( const String parameterName,
const String parameterValue 
) const

Returns a copy of this URL, with a GET or POST parameter added to the end.

Any control characters in the value will be encoded. e.g. calling "withParameter ("amount", "some fish") for the url "www.fish.com" would produce a new url whose toString(true) method would return "www.fish.com?amount=some+fish".

See also
getParameterNames, getParameterValues

Definition at line 778 of file juce_URL.cpp.

◆ withParameters()

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.

See also
withParameter

Definition at line 786 of file juce_URL.cpp.

◆ withPOSTData() [1/2]

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 you're setting the POST data, be careful not to have any parameters set as well, otherwise it'll all get thrown in together, and might not have the desired effect.

If the URL already contains some POST data, this will replace it, rather than being appended to it.

This data will only be used if you specify a post operation when you call createInputStream().

Definition at line 802 of file juce_URL.cpp.

◆ withPOSTData() [2/2]

URL juce::URL::withPOSTData ( const String postData) const

Returns a copy of this URL, with a block of data to send as the POST data.

If you're setting the POST data, be careful not to have any parameters set as well, otherwise it'll all get thrown in together, and might not have the desired effect.

If the URL already contains some POST data, this will replace it, rather than being appended to it.

This data will only be used if you specify a post operation when you call createInputStream().

Definition at line 797 of file juce_URL.cpp.

Referenced by withPOSTData().


The documentation for this class was generated from the following files: