Loading...
Searching...
No Matches
juce_URL.h
/*
==============================================================================
This file is part of the JUCE library.
Copyright (c) 2022 - Raw Material Software Limited
JUCE is an open source library subject to commercial or open-source
licensing.
The code included in this file is provided under the terms of the ISC license
http://www.isc.org/downloads/software-support-policy/isc-license. Permission
To use, copy, modify, and/or distribute this software for any purpose with or
without fee is hereby granted provided that the above copyright notice and
this permission notice appear in all copies.
JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
DISCLAIMED.
==============================================================================
*/
namespace juce
{
class WebInputStream;
//==============================================================================
class JUCE_API URL
{
public:
//==============================================================================
URL();
URL (const String& url);
explicit 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;
[[nodiscard]] URL withNewDomainAndPath (const String& newFullPath) const;
[[nodiscard]] URL withNewSubPath (const String& newPath) const;
URL getParentURL() const;
URL getChildURL (const String& subPath) const;
//==============================================================================
[[nodiscard]] URL withParameter (const String& parameterName,
const String& parameterValue) const;
[[nodiscard]] URL withParameters (const StringPairArray& parametersToAdd) const;
[[nodiscard]] URL withAnchor (const String& anchor) const;
[[nodiscard]] URL withFileToUpload (const String& parameterName,
const File& fileToUpload,
const String& mimeType) const;
[[nodiscard]] URL withDataToUpload (const String& parameterName,
const String& filename,
const MemoryBlock& fileContentToUpload,
const String& mimeType) const;
const StringArray& getParameterNames() const noexcept { return parameterNames; }
const StringArray& getParameterValues() const noexcept { return parameterValues; }
[[nodiscard]] URL withPOSTData (const String& postData) const;
[[nodiscard]] URL withPOSTData (const MemoryBlock& postData) const;
String getPostData() const { return postData.toString(); }
const MemoryBlock& getPostDataAsMemoryBlock() const noexcept { return postData; }
//==============================================================================
bool launchInDefaultBrowser() const;
//==============================================================================
static bool isProbablyAWebsiteURL (const String& possibleURL);
static bool isProbablyAnEmailAddress (const String& possibleEmailAddress);
//==============================================================================
enum class ParameterHandling
{
inAddress,
inPostData
};
class JUCE_API InputStreamOptions
{
public:
explicit InputStreamOptions (ParameterHandling parameterHandling);
//==============================================================================
[[nodiscard]] InputStreamOptions withProgressCallback (std::function<bool (int bytesSent, int totalBytes)> progressCallback) const;
[[nodiscard]] InputStreamOptions withExtraHeaders (const String& extraHeaders) const;
[[nodiscard]] InputStreamOptions withConnectionTimeoutMs (int connectionTimeoutMs) const;
[[nodiscard]] InputStreamOptions withResponseHeaders (StringPairArray* responseHeaders) const;
[[nodiscard]] InputStreamOptions withStatusCode (int* statusCode) const;
[[nodiscard]] InputStreamOptions withNumRedirectsToFollow (int numRedirectsToFollow) const;
[[nodiscard]] InputStreamOptions withHttpRequestCmd (const String& httpRequestCmd) const;
//==============================================================================
ParameterHandling getParameterHandling() const noexcept { return parameterHandling; }
std::function<bool (int, int)> getProgressCallback() const noexcept { return progressCallback; }
String getExtraHeaders() const noexcept { return extraHeaders; }
int getConnectionTimeoutMs() const noexcept { return connectionTimeOutMs; }
StringPairArray* getResponseHeaders() const noexcept { return responseHeaders; }
int* getStatusCode() const noexcept { return statusCode; }
int getNumRedirectsToFollow() const noexcept { return numRedirectsToFollow; }
String getHttpRequestCmd() const noexcept { return httpRequestCmd; }
private:
//==============================================================================
const ParameterHandling parameterHandling;
std::function<bool (int, int)> progressCallback = nullptr;
String extraHeaders;
int connectionTimeOutMs = 0;
StringPairArray* responseHeaders = nullptr;
int* statusCode = nullptr;
int numRedirectsToFollow = 5;
String httpRequestCmd;
};
std::unique_ptr<InputStream> createInputStream (const InputStreamOptions& options) const;
std::unique_ptr<OutputStream> createOutputStream() const;
//==============================================================================
class DownloadTask;
struct JUCE_API DownloadTaskListener
{
virtual ~DownloadTaskListener() = default;
virtual void finished (DownloadTask* task, bool success) = 0;
virtual void progress (DownloadTask* task, int64 bytesDownloaded, int64 totalLength);
};
class DownloadTaskOptions
{
public:
String extraHeaders;
String sharedContainer;
DownloadTaskListener* listener = nullptr;
bool usePost = false;
[[nodiscard]] auto withExtraHeaders (String value) const { return with (&DownloadTaskOptions::extraHeaders, std::move (value)); }
[[nodiscard]] auto withSharedContainer (String value) const { return with (&DownloadTaskOptions::sharedContainer, std::move (value)); }
[[nodiscard]] auto withListener (DownloadTaskListener* value) const { return with (&DownloadTaskOptions::listener, std::move (value)); }
[[nodiscard]] auto withUsePost (bool value) const { return with (&DownloadTaskOptions::usePost, value); }
private:
template <typename Member, typename Value>
[[nodiscard]] DownloadTaskOptions with (Member&& member, Value&& value) const
{
auto copy = *this;
copy.*member = std::forward<Value> (value);
return copy;
}
};
class JUCE_API DownloadTask
{
public:
using Listener = DownloadTaskListener;
virtual ~DownloadTask();
int64 getTotalLength() const { return contentLength; }
int64 getLengthDownloaded() const { return downloaded; }
bool isFinished() const { return finished; }
int statusCode() const { return httpCode; }
inline bool hadError() const { return error; }
File getTargetLocation() const { return targetLocation; }
protected:
int64 contentLength = -1, downloaded = 0;
bool finished = false, error = false;
int httpCode = -1;
File targetLocation;
DownloadTask();
private:
friend class URL;
static std::unique_ptr<DownloadTask> createFallbackDownloader (const URL&, const File&, const DownloadTaskOptions&);
public:
#if JUCE_IOS
static void juce_iosURLSessionNotify (const String&);
#endif
private:
JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (DownloadTask)
};
[[deprecated ("Use the overload with a DownloadTaskOptions argument instead")]]
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;
//==============================================================================
static String addEscapeChars (const String& stringToAddEscapeCharsTo,
bool isParameter,
bool roundBracketsAreLegal = true);
static String removeEscapeChars (const String& stringToRemoveEscapeCharsFrom);
static URL createWithoutParsing (const String& url);
//==============================================================================
#ifndef DOXYGEN
using OpenStreamProgressCallback = bool (void* context, int bytesSent, int totalBytes);
[[deprecated ("New code should use the method which takes an InputStreamOptions argument instead.")]]
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;
#endif
private:
//==============================================================================
#if JUCE_IOS
struct Bookmark : public ReferenceCountedObject
{
using Ptr = ReferenceCountedObjectPtr<Bookmark>;
Bookmark (void*);
~Bookmark();
void* data;
};
Bookmark::Ptr bookmark;
friend void setURLBookmark (URL&, void*);
friend void* getURLBookmark (URL&);
#endif
//==============================================================================
struct Upload : public ReferenceCountedObject
{
Upload (const String&, const String&, const String&, const File&, MemoryBlock*);
String parameterName, filename, mimeType;
File file;
std::unique_ptr<MemoryBlock> data;
JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (Upload)
};
//==============================================================================
friend class WebInputStream;
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;
static ParameterHandling toHandling (bool);
static File fileFromFileSchemeURL (const URL&);
String getDomainInternal (bool) const;
//==============================================================================
String url;
MemoryBlock postData;
StringArray parameterNames, parameterValues;
String anchor;
ReferenceCountedArray<Upload> filesToUpload;
//==============================================================================
JUCE_LEAK_DETECTOR (URL)
};
} // namespace juce
juce::File
Definition juce_File.h:45
juce::MemoryBlock
Definition juce_MemoryBlock.h:33
juce::StringArray
Definition juce_StringArray.h:35
juce::StringPairArray
Definition juce_StringPairArray.h:35
juce::String
Definition juce_String.h:53
juce::URL::DownloadTaskOptions
Definition juce_URL.h:460
juce::URL::DownloadTaskOptions::withSharedContainer
auto withSharedContainer(String value) const
Definition juce_URL.h:477
juce::URL::DownloadTaskOptions::withExtraHeaders
auto withExtraHeaders(String value) const
Definition juce_URL.h:468
juce::URL::DownloadTaskOptions::withListener
auto withListener(DownloadTaskListener *value) const
Definition juce_URL.h:480
juce::URL::DownloadTaskOptions::withUsePost
auto withUsePost(bool value) const
Definition juce_URL.h:483
juce::URL::DownloadTask
Definition juce_URL.h:500
juce::URL::DownloadTask::hadError
bool hadError() const
Definition juce_URL.h:530
juce::URL::DownloadTask::getLengthDownloaded
int64 getLengthDownloaded() const
Definition juce_URL.h:516
juce::URL::DownloadTask::isFinished
bool isFinished() const
Definition juce_URL.h:519
juce::URL::DownloadTask::getTargetLocation
File getTargetLocation() const
Definition juce_URL.h:533
juce::URL::DownloadTask::statusCode
int statusCode() const
Definition juce_URL.h:527
juce::URL::DownloadTask::getTotalLength
int64 getTotalLength() const
Definition juce_URL.h:513
juce::URL::InputStreamOptions
Definition juce_URL.h:331
juce::URL::InputStreamOptions::withExtraHeaders
InputStreamOptions withExtraHeaders(const String &extraHeaders) const
Definition juce_URL.cpp:704
juce::URL::InputStreamOptions::withResponseHeaders
InputStreamOptions withResponseHeaders(StringPairArray *responseHeaders) const
Definition juce_URL.cpp:714
juce::URL::InputStreamOptions::withStatusCode
InputStreamOptions withStatusCode(int *statusCode) const
Definition juce_URL.cpp:719
juce::URL::InputStreamOptions::withNumRedirectsToFollow
InputStreamOptions withNumRedirectsToFollow(int numRedirectsToFollow) const
Definition juce_URL.cpp:724
juce::URL::InputStreamOptions::withConnectionTimeoutMs
InputStreamOptions withConnectionTimeoutMs(int connectionTimeoutMs) const
Definition juce_URL.cpp:709
juce::URL::InputStreamOptions::InputStreamOptions
InputStreamOptions(ParameterHandling parameterHandling)
Definition juce_URL.cpp:697
juce::URL::InputStreamOptions::withProgressCallback
InputStreamOptions withProgressCallback(std::function< bool(int bytesSent, int totalBytes)> progressCallback) const
Definition juce_URL.cpp:699
juce::URL::InputStreamOptions::withHttpRequestCmd
InputStreamOptions withHttpRequestCmd(const String &httpRequestCmd) const
Definition juce_URL.cpp:729
juce::URL
Definition juce_URL.h:38
juce::URL::withParameter
URL withParameter(const String &parameterName, const String &parameterValue) const
Definition juce_URL.cpp:864
juce::URL::createWithoutParsing
static URL createWithoutParsing(const String &url)
Definition juce_URL.cpp:219
juce::URL::getLocalFile
File getLocalFile() const
Definition juce_URL.cpp:387
juce::URL::isWellFormed
bool isWellFormed() const
Definition juce_URL.cpp:332
juce::URL::readEntireBinaryStream
bool readEntireBinaryStream(MemoryBlock &destData, bool usePostCommand=false) const
Definition juce_URL.cpp:833
juce::URL::getPort
int getPort() const
Definition juce_URL.cpp:432
juce::URL::withDataToUpload
URL withDataToUpload(const String &parameterName, const String &filename, const MemoryBlock &fileContentToUpload, const String &mimeType) const
Definition juce_URL.cpp:929
juce::URL::getFileName
String getFileName() const
Definition juce_URL.cpp:392
juce::URL::getChildURL
URL getChildURL(const String &subPath) const
Definition juce_URL.cpp:466
juce::URL::removeEscapeChars
static String removeEscapeChars(const String &stringToRemoveEscapeCharsFrom)
Definition juce_URL.cpp:937
juce::URL::getAnchorString
String getAnchorString() const
Definition juce_URL.cpp:368
juce::URL::addEscapeChars
static String addEscapeChars(const String &stringToAddEscapeCharsTo, bool isParameter, bool roundBracketsAreLegal=true)
Definition juce_URL.cpp:966
juce::URL::withAnchor
URL withAnchor(const String &anchor) const
Definition juce_URL.cpp:883
juce::URL::toString
String toString(bool includeGetParameters) const
Definition juce_URL.cpp:319
juce::URL::createOutputStream
std::unique_ptr< OutputStream > createOutputStream() const
Definition juce_URL.cpp:812
juce::URL::getSubPath
String getSubPath(bool includeGetParameters=false) const
Definition juce_URL.cpp:343
juce::URL::getParentURL
URL getParentURL() const
Definition juce_URL.cpp:459
juce::URL::getQueryString
String getQueryString() const
Definition juce_URL.cpp:355
juce::URL::withNewSubPath
URL withNewSubPath(const String &newPath) const
Definition juce_URL.cpp:446
juce::URL::getPostDataAsMemoryBlock
const MemoryBlock & getPostDataAsMemoryBlock() const noexcept
Definition juce_URL.h:289
juce::URL::withNewDomainAndPath
URL withNewDomainAndPath(const String &newFullPath) const
Definition juce_URL.cpp:439
juce::URL::getPostData
String getPostData() const
Definition juce_URL.h:286
juce::URL::readEntireTextStream
String readEntireTextStream(bool usePostCommand=false) const
Definition juce_URL.cpp:847
juce::URL::isEmpty
bool isEmpty() const noexcept
Definition juce_URL.cpp:327
juce::URL::createInputStream
std::unique_ptr< InputStream > createInputStream(const InputStreamOptions &options) const
Definition juce_URL.cpp:735
juce::URL::getParameterValues
const StringArray & getParameterValues() const noexcept
Definition juce_URL.h:263
juce::URL::getDomain
String getDomain() const
Definition juce_URL.cpp:338
juce::URL::isLocalFile
bool isLocalFile() const
Definition juce_URL.cpp:382
juce::URL::withFileToUpload
URL withFileToUpload(const String &parameterName, const File &fileToUpload, const String &mimeType) const
Definition juce_URL.cpp:922
juce::URL::withParameters
URL withParameters(const StringPairArray &parametersToAdd) const
Definition juce_URL.cpp:872
juce::URL::getParameterNames
const StringArray & getParameterNames() const noexcept
Definition juce_URL.h:249
juce::URL::readEntireXmlStream
std::unique_ptr< XmlElement > readEntireXmlStream(bool usePostCommand=false) const
Definition juce_URL.cpp:858
juce::URL::getScheme
String getScheme() const
Definition juce_URL.cpp:376
juce::URL::downloadToFile
std::unique_ptr< DownloadTask > downloadToFile(const File &targetLocation, const DownloadTaskOptions &options)
juce::URL::URL
URL()
Definition juce_URL.cpp:138
juce::Value
Definition juce_Value.h:51
juce::WebInputStream
Definition juce_WebInputStream.h:33
juce::URL::DownloadTaskListener
Definition juce_URL.h:441
juce::URL::DownloadTaskListener::finished
virtual void finished(DownloadTask *task, bool success)=0
juce::URL::DownloadTaskListener::progress
virtual void progress(DownloadTask *task, int64 bytesDownloaded, int64 totalLength)
Definition juce_URL.cpp:109