juce_URL.h

Go to the documentation of this file.

 /*
  ==============================================================================
 
   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