juce_AndroidDocument.h

Go to the documentation of this file.

/*
  ==============================================================================
 
   This file is part of the JUCE library.
   Copyright (c) 2020 - 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 AndroidDocumentInfo
{
public:
    AndroidDocumentInfo() = default;

    bool exists() const                 { return isJuceFlagSet (flagExists); }

    bool isDirectory() const;

    bool isFile() const                 { return type.isNotEmpty() && ! isDirectory(); }

    bool canRead() const                { return isJuceFlagSet (flagHasReadPermission) && type.isNotEmpty(); }

    bool canWrite() const
    {
        return isJuceFlagSet (flagHasWritePermission)
               && type.isNotEmpty()
               && (isNativeFlagSet (flagSupportsWrite)
                   || isNativeFlagSet (flagSupportsDelete)
                   || isNativeFlagSet (flagDirSupportsCreate));
    }

    bool canDelete() const              { return isNativeFlagSet (flagSupportsDelete); }

    bool canCreateChildren() const      { return isNativeFlagSet (flagDirSupportsCreate); }

    bool canRename() const              { return isNativeFlagSet (flagSupportsRename); }

    bool canCopy() const                { return isNativeFlagSet (flagSupportsCopy); }

    bool canMove() const                { return isNativeFlagSet (flagSupportsMove); }

    bool isVirtual() const              { return isNativeFlagSet (flagVirtualDocument); }

    String getName() const              { return name; }

    String getType() const              { return isDirectory() ? String{} : type; }

    int64 getLastModified() const       { return isJuceFlagSet (flagValidModified) ? lastModified : 0; }

    bool isLastModifiedValid() const    { return isJuceFlagSet (flagValidModified); }

    int64 getSizeInBytes() const        { return isJuceFlagSet (flagValidSize) ? sizeInBytes : 0; }

    bool isSizeInBytesValid() const     { return isJuceFlagSet (flagValidSize); }

    class Args;
 
private:
    explicit AndroidDocumentInfo (Args);
 
    bool isNativeFlagSet (int flag) const { return (nativeFlags & flag) != 0; }
    bool isJuceFlagSet   (int flag) const { return (juceFlags   & flag) != 0; }
 
    /*  Native Android flags that might be set in the COLUMN_FLAGS for a particular document */
    enum
    {
        flagSupportsWrite       = 0x0002,
        flagSupportsDelete      = 0x0004,
        flagDirSupportsCreate   = 0x0008,
        flagSupportsRename      = 0x0040,
        flagSupportsCopy        = 0x0080,
        flagSupportsMove        = 0x0100,
        flagVirtualDocument     = 0x0200,
    };
 
    /*  Flags for other binary properties that aren't exposed in COLUMN_FLAGS */
    enum
    {
        flagExists              = 1 << 0,
        flagValidModified       = 1 << 1,
        flagValidSize           = 1 << 2,
        flagHasReadPermission   = 1 << 3,
        flagHasWritePermission  = 1 << 4,
    };
 
    String name;
    String type;
    int64 lastModified = 0;
    int64 sizeInBytes  = 0;
    int nativeFlags = 0, juceFlags = 0;
};
 
//==============================================================================
class AndroidDocumentPermission
{
public:
    URL getUrl() const                          { return url; }

    int64 getPersistedTime() const              { return time; }

    bool isReadPermission() const               { return read; }

    bool isWritePermission() const              { return write; }

    static void takePersistentReadWriteAccess (const URL&);

    static void releasePersistentReadWriteAccess (const URL&);

    static std::vector<AndroidDocumentPermission> getPersistedPermissions();
 
private:
    URL url;
    int64 time = 0;
    bool read = false, write = false;
};
 
//==============================================================================
class AndroidDocument
{
public:
    AndroidDocument();

    static AndroidDocument fromFile (const File& filePath);

    static AndroidDocument fromDocument (const URL& documentUrl);

    static AndroidDocument fromTree (const URL& treeUrl);
 
    AndroidDocument (const AndroidDocument&);
    AndroidDocument (AndroidDocument&&) noexcept;
 
    AndroidDocument& operator= (const AndroidDocument&);
    AndroidDocument& operator= (AndroidDocument&&) noexcept;
 
    ~AndroidDocument();

    bool operator== (const AndroidDocument&) const;

    bool operator!= (const AndroidDocument&) const;

    bool deleteDocument() const;

    bool renameTo (const String& newDisplayName);

    AndroidDocument createChildDocumentWithTypeAndName (const String& type, const String& name) const;

    AndroidDocument createChildDirectory (const String& name) const;

    bool hasValue() const               { return pimpl != nullptr; }

    explicit operator bool() const      { return hasValue(); }

    std::unique_ptr<InputStream>  createInputStream()  const;

    std::unique_ptr<OutputStream> createOutputStream() const;

    URL getUrl() const;

    AndroidDocumentInfo getInfo() const;

    AndroidDocument copyDocumentToParentDocument (const AndroidDocument& target) const;

    bool moveDocumentFromParentToParent (const AndroidDocument& currentParent,
                                         const AndroidDocument& newParent);

    struct NativeInfo;

    NativeInfo getNativeInfo() const;
 
private:
    struct Utils;
    class Pimpl;
 
    explicit AndroidDocument (std::unique_ptr<Pimpl>);
 
    void swap (AndroidDocument& other) noexcept { std::swap (other.pimpl, pimpl); }
 
    std::unique_ptr<Pimpl> pimpl;
};
 
//==============================================================================
class AndroidDocumentIterator final
{
public:
    using difference_type = std::ptrdiff_t;
    using pointer = void;
    using iterator_category = std::input_iterator_tag;

    static AndroidDocumentIterator makeNonRecursive (const AndroidDocument&);

    static AndroidDocumentIterator makeRecursive (const AndroidDocument&);

    AndroidDocumentIterator() = default;
 
    bool operator== (const AndroidDocumentIterator& other) const noexcept { return pimpl == nullptr && other.pimpl == nullptr; }
    bool operator!= (const AndroidDocumentIterator& other) const noexcept { return ! operator== (other); }

    AndroidDocument operator*() const;

    AndroidDocumentIterator& operator++();

    AndroidDocumentIterator begin() const { return *this; }

    AndroidDocumentIterator end()   const { return AndroidDocumentIterator{}; }
 
private:
    struct Utils;
    struct Pimpl;
 
    explicit AndroidDocumentIterator (std::unique_ptr<Pimpl>);
 
    std::shared_ptr<Pimpl> pimpl;
};
 
} // namespace juce