#include <juce_URL.h>

Classes
class	InputStreamOptions
struct	DownloadTaskListener
class	DownloadTaskOptions
class	DownloadTask
struct	Upload

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	getScheme () const
bool	isLocalFile () const
File	getLocalFile () const
String	getFileName () const
int	getPort () const
JUCE_NODISCARD URL	withNewDomainAndPath (const String &newFullPath) const
JUCE_NODISCARD URL	withNewSubPath (const String &newPath) const
URL	getParentURL () const
URL	getChildURL (const String &subPath) const
JUCE_NODISCARD URL	withParameter (const String &parameterName, const String &parameterValue) const
JUCE_NODISCARD URL	withParameters (const StringPairArray &parametersToAdd) const
JUCE_NODISCARD URL	withFileToUpload (const String &parameterName, const File &fileToUpload, const String &mimeType) const
JUCE_NODISCARD URL	withDataToUpload (const String &parameterName, const String &filename, const MemoryBlock &fileContentToUpload, const String &mimeType) const
const StringArray &	getParameterNames () const noexcept
const StringArray &	getParameterValues () const noexcept
JUCE_NODISCARD URL	withPOSTData (const String &postData) const
JUCE_NODISCARD 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)

Private Member Functions
	URL (const String &, int)
void	init ()
void	addParameter (const String &, const String &)
bool	hasBodyDataToSend () const
void	createHeadersAndPostData (String &, MemoryBlock &, bool) const
URL	withUpload (Upload *) const
String	getDomainInternal (bool) const

Static Private Member Functions
static ParameterHandling	toHandling (bool)
static File	fileFromFileSchemeURL (const URL &)

Private Attributes
String	url
MemoryBlock	postData
StringArray	parameterNames
StringArray	parameterValues
ReferenceCountedArray< Upload >	filesToUpload

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

@tags{Core}

Member Typedef Documentation

◆ OpenStreamProgressCallback

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

Member Enumeration Documentation

◆ ParameterHandling

enum class juce::URL::ParameterHandling

strong

Enumerator
inAddress
inPostData

Constructor & Destructor Documentation

◆ URL() [1/4]

juce::URL::URL ( )

Creates an empty URL.

◆ URL() [2/4]

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

◆ URL() [3/4]

juce::URL::URL ( File localFile )

explicit

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

◆ URL() [4/4]

juce::URL::URL	(	const String &	u,
		int	)

private

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

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 juce::URL::addParameter	(	const String &	name,
		const String &	value )

private

◆ createHeadersAndPostData()

void juce::URL::createHeadersAndPostData	(	String &	headers,
		MemoryBlock &	postDataToWrite,
		bool	addParametersToBody ) const

private

◆ createInputStream() [1/2]

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.

See also: InputStreamOptions

◆ createInputStream() [2/2]

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.

Parameters

Options a set of options that will be used when opening the stream.

Returns: a valid input stream, or nullptr if there was an error trying to open it.

◆ createOutputStream()

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.

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

◆ downloadToFile() [1/2]

std::unique_ptr< URL::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.

◆ downloadToFile() [2/2]

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.

◆ fileFromFileSchemeURL()

File juce::URL::fileFromFileSchemeURL ( const URL & fileURL )

staticprivate

◆ 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

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

◆ getDomainInternal()

String juce::URL::getDomainInternal ( bool ignorePort ) const

private

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

◆ 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

◆ 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

◆ 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

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

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

◆ getPostData()

String juce::URL::getPostData ( ) const

inline

Returns the data that was set using withPOSTData().

◆ getPostDataAsMemoryBlock()

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

inlinenoexcept

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

◆ getQueryString()

String juce::URL::getQueryString ( ) const

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

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

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

Parameters

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.

See also: getQueryString

◆ hasBodyDataToSend()

bool juce::URL::hasBodyDataToSend ( ) const

private

◆ init()

void juce::URL::init ( )

private

◆ isEmpty()

bool juce::URL::isEmpty ( ) const

noexcept

Returns true if the URL is an empty string.

◆ isLocalFile()

bool juce::URL::isLocalFile ( ) const

Returns true if this URL refers to a local file.

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

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

◆ isWellFormed()

bool juce::URL::isWellFormed ( ) const

True if it seems to be valid.

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

◆ operator!=()

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

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

◆ 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

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

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

See also: readEntireBinaryStream, 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.

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

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

◆ toHandling()

URL::ParameterHandling juce::URL::toHandling ( bool usePostData )

staticprivate

◆ toString()

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

Returns a string version of the URL.

Parameters

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.

See also: getQueryString

◆ 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

◆ 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

◆ 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

◆ 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

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

See also: getParameterNames, getParameterValues

◆ 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

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

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

◆ withUpload()

URL juce::URL::withUpload ( Upload * f ) const

private

◆ WebInputStream

friend class WebInputStream

friend

Member Data Documentation

◆ filesToUpload

ReferenceCountedArray<Upload> juce::URL::filesToUpload

private

◆ parameterNames

StringArray juce::URL::parameterNames

private

◆ parameterValues

StringArray juce::URL::parameterValues

private

◆ postData

MemoryBlock juce::URL::postData

private

◆ url

String juce::URL::url

private

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

/home/runner/work/lmms-fork/lmms-fork/plugins/CarlaBase/carla/source/modules/juce_core/network/juce_URL.h
/home/runner/work/lmms-fork/lmms-fork/plugins/CarlaBase/carla/source/modules/juce_core/native/juce_curl_Network.cpp
/home/runner/work/lmms-fork/lmms-fork/plugins/CarlaBase/carla/source/modules/juce_core/native/juce_linux_Network.cpp
/home/runner/work/lmms-fork/lmms-fork/plugins/CarlaBase/carla/source/modules/juce_core/native/juce_win32_Network.cpp
/home/runner/work/lmms-fork/lmms-fork/plugins/CarlaBase/carla/source/modules/juce_core/network/juce_URL.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ OpenStreamProgressCallback

Member Enumeration Documentation

◆ ParameterHandling

Constructor & Destructor Documentation

◆ URL() [1/4]

◆ URL() [2/4]

◆ URL() [3/4]

◆ URL() [4/4]

Member Function Documentation

◆ addEscapeChars()

◆ addParameter()

◆ createHeadersAndPostData()

◆ createInputStream() [1/2]

◆ createInputStream() [2/2]

◆ createOutputStream()

◆ createWithoutParsing()

◆ downloadToFile() [1/2]

◆ downloadToFile() [2/2]

◆ fileFromFileSchemeURL()

◆ getChildURL()

◆ getDomain()

◆ getDomainInternal()

◆ getFileName()

◆ getLocalFile()

◆ getParameterNames()

◆ getParameterValues()

◆ getParentURL()

◆ getPort()

◆ getPostData()

◆ getPostDataAsMemoryBlock()

◆ getQueryString()

◆ getScheme()

◆ getSubPath()

◆ hasBodyDataToSend()

◆ init()

◆ isEmpty()

◆ isLocalFile()

◆ isProbablyAnEmailAddress()

◆ isProbablyAWebsiteURL()

◆ isWellFormed()

◆ launchInDefaultBrowser()

◆ operator!=()

◆ operator==()

◆ readEntireBinaryStream()

◆ readEntireTextStream()

◆ readEntireXmlStream()

◆ removeEscapeChars()

◆ toHandling()

◆ toString()

◆ withDataToUpload()

◆ withFileToUpload()

◆ withNewDomainAndPath()

◆ withNewSubPath()

◆ withParameter()

◆ withParameters()

◆ withPOSTData() [1/2]

◆ withPOSTData() [2/2]

◆ withUpload()

Friends And Related Symbol Documentation

◆ WebInputStream

Member Data Documentation

◆ filesToUpload

◆ parameterNames

◆ parameterValues

◆ postData

◆ url