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 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       { return parameterNames; }

    const StringArray& getParameterValues() const noexcept      { return parameterValues; }

    JUCE_NODISCARD URL withPOSTData (const String& postData) const;

    JUCE_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);
 
        //==============================================================================
        JUCE_NODISCARD InputStreamOptions withProgressCallback (std::function<bool (int bytesSent, int totalBytes)> progressCallback) const;

        JUCE_NODISCARD InputStreamOptions withExtraHeaders (const String& extraHeaders) const;

        JUCE_NODISCARD InputStreamOptions withConnectionTimeoutMs (int connectionTimeoutMs) const;

        JUCE_NODISCARD InputStreamOptions withResponseHeaders (StringPairArray* responseHeaders) const;

        JUCE_NODISCARD InputStreamOptions withStatusCode (int* statusCode) const;

        JUCE_NODISCARD InputStreamOptions withNumRedirectsToFollow (int numRedirectsToFollow) const;

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

        JUCE_NODISCARD auto withExtraHeaders (String value) const            { return with (&DownloadTaskOptions::extraHeaders, std::move (value)); }

        JUCE_NODISCARD auto withSharedContainer (String value) const         { return with (&DownloadTaskOptions::sharedContainer, std::move (value)); }

        JUCE_NODISCARD auto withListener (DownloadTaskListener* value) const { return with (&DownloadTaskOptions::listener, std::move (value)); }

        JUCE_NODISCARD auto withUsePost (bool value) const                   { return with (&DownloadTaskOptions::usePost, value); }
 
    private:
        template <typename Member, typename Value>
        JUCE_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;
 
    ReferenceCountedArray<Upload> filesToUpload;
 
    //==============================================================================
    JUCE_LEAK_DETECTOR (URL)
};
 
} // namespace juce