Represents a URL and has a bunch of useful functions to manipulate it. More...

#include <juce_URL.h>

Collaboration diagram for URL:

[legend]

Classes
class	DownloadTask
	Represents a download task. More...

struct	Upload

Public Types
typedef bool()	OpenStreamProgressCallback(void *context, int bytesSent, int totalBytes)
	This callback function can be used by the createInputStream() method. More...

Public Member Functions
	URL ()
	Creates an empty URL. More...

	URL (const String &url)
	Creates a URL from a string. More...

	URL (const URL &other)
	Creates a copy of another URL. More...

	~URL ()
	Destructor. More...

WebInputStream *	createInputStream (bool doPostLikeRequest, OpenStreamProgressCallback progressCallback=nullptr, void progressCallbackContext=nullptr, String extraHeaders=String(), int connectionTimeOutMs=0, StringPairArray responseHeaders=nullptr, int statusCode=nullptr, int numRedirectsToFollow=5, String httpRequestCmd=String()) const
	Attempts to open a stream that can read from this URL. More...

DownloadTask *	downloadToFile (const File &targetLocation, String extraHeaders=String(), DownloadTask::Listener *listener=nullptr)
	Download the URL to a file. More...

URL	getChildURL (const String &subPath) const
	Returns a new URL that refers to a sub-path relative to this one. More...

String	getDomain () const
	Returns just the domain part of the URL. More...

const StringArray &	getParameterNames () const noexcept
	Returns an array of the names of all the URL's parameters. More...

const StringArray &	getParameterValues () const noexcept
	Returns an array of the values of all the URL's parameters. More...

int	getPort () const
	Attempts to read a port number from the URL. More...

String	getPostData () const noexcept
	Returns the data that was set using withPOSTData(). More...

const MemoryBlock &	getPostDataAsMemoryBlock () const noexcept
	Returns the data that was set using withPOSTData() as MemoryBlock. More...

String	getScheme () const
	Returns the scheme of the URL. More...

String	getSubPath () const
	Returns the path part of the URL. More...

bool	isEmpty () const noexcept
	Returns true if the URL is an empty string. More...

bool	isWellFormed () const
	True if it seems to be valid. More...

bool	launchInDefaultBrowser () const
	Tries to launch the system's default browser to open the URL. More...

bool	operator!= (const URL &) const

URL &	operator= (const URL &other)
	Copies this URL from another one. More...

bool	operator== (const URL &) const
	Compares two URLs. More...

bool	readEntireBinaryStream (MemoryBlock &destData, bool usePostCommand=false) const
	Tries to download the entire contents of this URL into a binary data block. More...

String	readEntireTextStream (bool usePostCommand=false) const
	Tries to download the entire contents of this URL as a string. More...

XmlElement *	readEntireXmlStream (bool usePostCommand=false) const
	Tries to download the entire contents of this URL and parse it as XML. More...

String	toString (bool includeGetParameters) const
	Returns a string version of the URL. More...

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

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

URL	withNewDomainAndPath (const String &newFullPath) const
	Returns a new version of this URL with a different domain and path. More...

URL	withNewSubPath (const String &newPath) const
	Returns a new version of this URL with a different sub-path. More...

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

URL	withParameters (const StringPairArray &parametersToAdd) const
	Returns a copy of this URL, with a set of GET or POST parameters added. More...

URL	withPOSTData (const String &postData) const
	Returns a copy of this URL, with a block of data to send as the POST data. More...

URL	withPOSTData (const MemoryBlock &postData) const
	Returns a copy of this URL, with a block of data to send as the POST data. More...

Static Public Member Functions
static String	addEscapeChars (const String &stringToAddEscapeCharsTo, bool isParameter, bool roundBracketsAreLegal=true)
	Adds escape sequences to a string to encode any characters that aren't legal in a URL. More...

static URL	createWithoutParsing (const String &url)
	Returns a URL without attempting to remove any embedded parameters from the string. More...

static bool	isProbablyAnEmailAddress (const String &possibleEmailAddress)
	Takes a guess as to whether a string might be a valid email address. More...

static bool	isProbablyAWebsiteURL (const String &possibleURL)
	Takes a guess as to whether a string might be a valid website address. More...

static String	removeEscapeChars (const String &stringToRemoveEscapeCharsFrom)
	Replaces any escape character sequences in a string with their original character codes. More...

Private Member Functions
	URL (const String &, int)

void	addParameter (const String &, const String &)

void	createHeadersAndPostData (String &, MemoryBlock &) const

URL	withUpload (Upload *) const

Private Attributes
ReferenceCountedArray< Upload >	filesToUpload

StringArray	parameterNames

StringArray	parameterValues

MemoryBlock	postData

String	url

Friends
struct	ContainerDeletePolicy< Upload >

class	WebInputStream

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.

Member Typedef Documentation

◆ OpenStreamProgressCallback

typedef bool() URL::OpenStreamProgressCallback(void *context, int bytesSent, int totalBytes)

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.

Constructor & Destructor Documentation

◆ URL() [1/4]

URL::URL ( )

Creates an empty URL.

◆ URL() [2/4]

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

◆ URL() [3/4]

URL::URL ( const URL & other )

Creates a copy of another URL.

◆ ~URL()

URL::~URL ( )

Destructor.

◆ URL() [4/4]

URL::URL	(	const String &	,
		int
	)

private

Member Function Documentation

◆ addEscapeChars()

static String 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

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.

See also: removeEscapeChars

◆ addParameter()

void URL::addParameter	(	const String &	,
		const String &
	)

private

◆ createHeadersAndPostData()

void URL::createHeadersAndPostData	(	String &	,
		MemoryBlock &
	)		const

private

◆ createInputStream()

WebInputStream* URL::createInputStream	(	bool	doPostLikeRequest,
		OpenStreamProgressCallback *	progressCallback = `nullptr`,
		void *	progressCallbackContext = `nullptr`,
		String	extraHeaders = `String()`,
		int	connectionTimeOutMs = `0`,
		StringPairArray *	responseHeaders = `nullptr`,
		int *	statusCode = `nullptr`,
		int	numRedirectsToFollow = `5`,
		String	httpRequestCmd = `String()`
	)		const

Attempts to open a stream that can read from this URL.

This method is a convenience wrapper for creating a new WebInputStream and setting some commonly used options. The returned WebInputStream will have already been connected and reading can start instantly.

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.

Parameters

doPostLikeRequest	if 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).
progressCallback	if 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.
progressCallbackContext	if a callback is specified, this value will be passed to the function
extraHeaders	if 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.
connectionTimeOutMs	if 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.
responseHeaders	if this is non-null, all the (key, value) pairs received as headers in the response will be stored in this array
statusCode	if 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
numRedirectsToFollow	specifies the number of redirects that will be followed before returning a response (ignored for Android which follows up to 5 redirects)
httpRequestCmd	Specify 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.

◆ createWithoutParsing()

static URL 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.

◆ downloadToFile()

DownloadTask* URL::downloadToFile	(	const File &	targetLocation,
		String	extraHeaders = `String()`,
		DownloadTask::Listener *	listener = `nullptr`
	)

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 but are limited to simple GET requests.

◆ getChildURL()

URL 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

◆ getDomain()

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

◆ getParameterNames()

const StringArray& 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

◆ getParameterValues()

const StringArray& 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

◆ getPort()

int URL::getPort ( ) const

Attempts to read a port number from the URL.

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

◆ getPostData()

String URL::getPostData ( ) const

inlinenoexcept

Returns the data that was set using withPOSTData().

References MemoryBlock::toString().

◆ getPostDataAsMemoryBlock()

const MemoryBlock& URL::getPostDataAsMemoryBlock ( ) const

inlinenoexcept

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

◆ getScheme()

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

◆ getSubPath()

String URL::getSubPath ( ) const

Returns the path part of the URL.

E.g. for "http://www.xyz.com/foo/bar?x=1", this will return "foo/bar".

◆ isEmpty()

bool URL::isEmpty ( ) const

noexcept

Returns true if the URL is an empty string.

◆ isProbablyAnEmailAddress()

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

static

Takes a guess as to whether a string might be a valid email address.

This isn't foolproof!

◆ isProbablyAWebsiteURL()

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

static

Takes a guess as to whether a string might be a valid website address.

This isn't foolproof!

◆ isWellFormed()

bool URL::isWellFormed ( ) const

True if it seems to be valid.

◆ launchInDefaultBrowser()

bool URL::launchInDefaultBrowser ( ) const

Tries to launch the system's default browser to open the URL.

Returns true if this seems to have worked.

◆ operator!=()

bool URL::operator!= ( const URL & ) const

◆ operator=()

URL& URL::operator= ( const URL & other )

Copies this URL from another one.

◆ operator==()

bool URL::operator== ( const URL & ) const

Compares two URLs.

All aspects of the URLs must be identical for them to match, including any parameters, upload files, etc.

◆ readEntireBinaryStream()

bool 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

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)

See also: readEntireTextStream, readEntireXmlStream

◆ readEntireTextStream()

String 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

usePostCommand whether to use a POST command to get the data (uses a GET command if this is false)

See also: readEntireBinaryStream, readEntireXmlStream

◆ readEntireXmlStream()

XmlElement* 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 responsibile 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

usePostCommand whether to use a POST command to get the data (uses a GET command if this is false)

See also: readEntireBinaryStream, readEntireTextStream

◆ removeEscapeChars()

static String 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

◆ toString()

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

Referenced by VideoComponent::Pimpl::load().

◆ withDataToUpload()

URL 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

◆ withFileToUpload()

URL 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

◆ withNewDomainAndPath()

URL 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

◆ withNewSubPath()

URL 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

◆ withParameter()

URL 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

◆ withParameters()

URL 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

◆ withPOSTData() [1/2]

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

◆ withPOSTData() [2/2]

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

◆ withUpload()

URL URL::withUpload ( Upload * ) const

private

Friends And Related Function Documentation

◆ ContainerDeletePolicy< Upload >

friend struct ContainerDeletePolicy< Upload >

friend

◆ WebInputStream

friend class WebInputStream

friend

Member Data Documentation

◆ filesToUpload

ReferenceCountedArray<Upload> URL::filesToUpload

private

◆ parameterNames

StringArray URL::parameterNames

private

◆ parameterValues

StringArray URL::parameterValues

private

◆ postData

MemoryBlock URL::postData

private

◆ url

String URL::url

private

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

juce_URL.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ OpenStreamProgressCallback

Constructor & Destructor Documentation

◆ URL() [1/4]

◆ URL() [2/4]

◆ URL() [3/4]

◆ ~URL()

◆ URL() [4/4]

Member Function Documentation

◆ addEscapeChars()

◆ addParameter()

◆ createHeadersAndPostData()

◆ createInputStream()

◆ createWithoutParsing()

◆ downloadToFile()

◆ getChildURL()

◆ getDomain()

◆ getParameterNames()

◆ getParameterValues()

◆ getPort()

◆ getPostData()

◆ getPostDataAsMemoryBlock()

◆ getScheme()

◆ getSubPath()

◆ isEmpty()

◆ isProbablyAnEmailAddress()

◆ isProbablyAWebsiteURL()

◆ isWellFormed()

◆ launchInDefaultBrowser()

◆ operator!=()

◆ operator=()

◆ operator==()

◆ readEntireBinaryStream()

◆ readEntireTextStream()

◆ readEntireXmlStream()

◆ removeEscapeChars()

◆ toString()

◆ withDataToUpload()

◆ withFileToUpload()

◆ withNewDomainAndPath()

◆ withNewSubPath()

◆ withParameter()

◆ withParameters()

◆ withPOSTData() [1/2]

◆ withPOSTData() [2/2]

◆ withUpload()

Friends And Related Function Documentation

◆ ContainerDeletePolicy< Upload >

◆ WebInputStream

Member Data Documentation

◆ filesToUpload

◆ parameterNames

◆ parameterValues

◆ postData

◆ url