import { ByteVector } from "./byteVector";
import { IFileAbstraction } from "./fileAbstraction";
import { IDisposable } from "./interfaces";
import { Properties } from "./properties";
import { SeekOrigin } from "./stream";
import { Tag, TagTypes } from "./tag";
/**
 * Specifies the options to use when reading the media. Can be treated as flags.
 */
export declare enum ReadStyle {
    /**
     * The media properties will not be read.
     */
    None = 0,
    /**
     * The media properties will be read with average accuracy.
     */
    Average = 2,
    /**
     * Use the {@link PictureLazy} class in the property {@link Tag.pictures}. This will avoid
     * loading picture content when reading the tag. Picture will be read lazily, when the picture
     * content is accessed.
     */
    PictureLazy = 4
}
/**
 * Specifies the type of file access operations currently permitted on an instance of {@link File}
 */
export declare enum FileAccessMode {
    /**
     * Read operations can be performed.
     */
    Read = 0,
    /**
     * Read and write operations can be performed
     */
    Write = 1,
    /**
     * The file is closed for both read and write operations
     */
    Closed = 2
}
/**
 * Delegate is used for intervening in {@link File.createFromPath} by resolving the filetype before
 * any standard resolution operations.
 * @remarks
 *     A FileTypeResolver is one way of altering the behavior of
 *     {@link File.createFromPath} When {@link File.createFromPath} is called, the registered
 *     resolvers are invoked in reverse order in which they were registered. The resolver may then
 *     perform any operations necessary, including other type-finding methods. If the resolver
 *     returns a new {@link File} it will instantly be returned, by {@link File.createFromPath}. If
 *     it returns `undefined`, {@link File.createFromPath} will continue to process. If the resolver
 *     throws an exception, it will be uncaught. To register a resolver, use
 *     {@link File.addFileTypeResolver}.
 * @param abstraction File to be read.
 * @param mimeType MimeType of the file.
 * @param style How to read media properties from the file
 * @returns New instance of {@link File} or `undefined` if the resolver could not be matched
 */
export declare type FileTypeResolver = (abstraction: IFileAbstraction, mimetype: string, style: ReadStyle) => File;
export declare type FileTypeConstructor = new (abstraction: IFileAbstraction, style: ReadStyle) => File;
/**
 * This abstract class provides a basic framework for reading and writing to a file, as well as
 * accessing basic tagging and media properties.
 * @remarks
 *     This class is agnostic to all specific media types. Its child classes, on the other
 *     hand, support the intricacies of different media and tagging formats. For example
 *     {@link Mpeg4File} supports the MPEG-4 specification and Apple's tagging format. Each file
 *     type can be created using its format specific constructors, but the preferred method is to
 *     use {@link File.createFromPath} or {@link File.createFromAbstraction} as it automatically
 *     detects the appropriate class from the file extension or provided MimeType.
 */
export declare abstract class File implements IDisposable {
    private static readonly BUFFER_SIZE;
    private static _fileTypes;
    private static _fileTypeResolvers;
    private readonly _fileAbstraction;
    private _fileStream;
    private _tagTypesOnDisk;
    private _corruptionReasons;
    private _mimeType;
    protected constructor(file: IFileAbstraction | string);
    /**
     * Creates a new instance of a {@link File} subclass for a specified file abstraction, MimeType,
     * and property read style.
     * @param abstraction Object to use when reading/writing from the current instance.
     * @param mimeType Optional, MimeType to use for determining the subclass of {@link File} to
     *     return. If omitted, the MimeType will be guessed based on the file's extension.
     * @param propertiesStyle Optional, level of detail to use when reading the media information
     *     from the new instance. If omitted, {@link ReadStyle.Average} is used.
     * @returns New instance of {@link File} as read from the specified abstraction.
     */
    static createFromAbstraction(abstraction: IFileAbstraction, mimeType?: string, propertiesStyle?: ReadStyle): File;
    /**
     * Creates a new instance of {@link File} subclass for a specified file path, MimeType, and
     * property read style.
     * @param filePath Path to the file to read/write.
     * @param mimeType Optional, MimeType to use for determining the subclass of {@link File} to
     *     return. If omitted, the MimeType will be guessed based on the file's extension.
     * @param propertiesStyle Optional, level of detail to use when reading the media information
     *     from the new instance. If omitted {@link ReadStyle.Average} is used.
     * @returns New instance of {@link File} as read from the specified path.
     */
    static createFromPath(filePath: string, mimeType?: string, propertiesStyle?: ReadStyle): File;
    private static createInternal;
    /**
     * Gets the buffer size to use when reading large blocks of data
     */
    static get bufferSize(): number;
    /**
     * Reasons for which this file is marked as corrupt.
     */
    get corruptionReasons(): string[];
    /**
     * Gets the {@link IFileAbstraction} representing the file.
     */
    get fileAbstraction(): IFileAbstraction;
    /**
     * Shortcut property to determine if a file has tags in memory.
     * NOTE: Just because `tag !== undefined` does not mean there are tags in memory.
     */
    get hasTags(): boolean;
    /**
     * Indicates whether this file may be corrupt. Files with unknown corruptions should not
     * be written.
     */
    get isPossiblyCorrupt(): boolean;
    /**
     * Indicates whether tags can be written back to the current file.
     */
    get isWritable(): boolean;
    /**
     * Gets the length of the file represented by the current instance. Value will be 0 if the file
     * is not open for reading;
     */
    get length(): number;
    /**
     * Gets the MimeType of the file as determined during creation of the instance.
     */
    get mimeType(): string;
    /**
     * Gets the file access mode in use by the current instance.
     */
    get mode(): FileAccessMode;
    /**
     * Sets the file access mode in use by the current instance. Changing the value will cause the
     * stream currently in use to be closed, except when a change is made from
     * {@link FileAccessMode.Write} to {@link FileAccessMode.Read} which has no effect.
     * @param val File access mode to change to
     */
    set mode(val: FileAccessMode);
    /**
     * Gets the name of the file as stored in its file abstraction.
     */
    get name(): string;
    /**
     * Gets the seek position in the internal stream used by the current instance. Value will be 0
     * if the file is not open for reading
     */
    get position(): number;
    /**
     * Gets the media properties of the file represented by the current instance.
     */
    abstract get properties(): Properties;
    /**
     * Gets an abstract representation of all tags stored in the current instance.
     * @remarks
     *     This property provides generic and general access to the most common tagging
     *     features of a file. To access or add a specific type of tag in the file, use
     *     {@link File.getTag}.
     */
    abstract get tag(): Tag;
    /**
     * Gets the tag types contained in the current instance.
     */
    get tagTypes(): TagTypes;
    /**
     * Gets the tag types contained in the physical file represented by the current instance.
     */
    get tagTypesOnDisk(): TagTypes;
    /**
     * Sets the tag types contained in the physical file represented by the current instance.
     * @param value
     * @protected
     */
    protected set tagTypesOnDisk(value: TagTypes);
    /**
     * Registers the constructor for a subclass of {@link File} with the MimeType it is associated
     * with. Optionally, the MimeType can be forcefully overridden if it was already registered.
     * @param mimeType MimeType to register this subclass constructor to.
     * @param constructor Constructor for a subclass of {@link File} that will be called if a file
     *     with a MimeType of `mimeType` is created.
     * @param override If `true` and a subclass of {@link File} was already registered to
     *     `mimeType`, it will be forcefully overridden. If `false`, an `Error` will be
     *     thrown if a subclass already registered to the MimeType.
     */
    static addFileType(mimeType: string, constructor: FileTypeConstructor, override?: boolean): void;
    /**
     * Registers a {@link FileTypeResolver} to the front of the list of file type resolvers.
     * @param resolver Function to handle resolving a subclass of {@link File} from an
     *     {@link IFileAbstraction}
     */
    static addFileTypeResolver(resolver: FileTypeResolver): void;
    /**
     * Used for removing a file type constructor during unit testing
     */
    static removeFileType(mimeType: string): void;
    /**
     * Used for removing a file type resolver during unit testing
     */
    static removeFileTypeResolver(resolver: FileTypeResolver): void;
    /**
     * Dispose the current instance. Equivalent to setting the mode to closed.
     */
    dispose(): void;
    /**
     * Searches forward through a file for a specified pattern, starting at a specified offset.
     * @param pattern Pattern to search for in the current instance. Must be smaller than the
     * @param startPosition Seek position to start searching. Must be positive, safe integer.
     * @param before Optional pattern that the searched for pattern must appear before. If this
     *     pattern is found first, `-1` is returned.
     * @throws Error Thrown if `pattern` is not provided or `startPosition` is not a
     *     positive, safe integer.
     * @returns Index at which the value was found. If not found, `-1` is returned.
     */
    find(pattern: ByteVector, startPosition?: number, before?: ByteVector): number;
    /**
     * Gets a tag of the specified type from the current instance, optionally creating a new tag if
     * possible.
     * @param types Type of tag to read.
     * @param create Whether or not to try and create the tag if one is not found. `true` does not
     *     guarantee the tag will be created. For example, trying to create an ID3v2 tag on an OGG
     *     Vorbis file will always fail.
     * @returns
     *     Tag object containing the tag that was found in or added to the current instance.
     *     If no matching tag was found and none was created, `undefined` is returned. It is safe
     *     to assume that if `undefined` is not returned, the returned tag can be cast to the
     *     appropriate type.
     * @example ```
     *     id3 = file.getTag(TagTypes.ID3v2, true);
     *     if (id3) { (<ID3v2.Tag> id3).setTextFrame("TMOO", moods); }
     *
     *     asf = file.getTag(TagTypes.Asf, true);
     *     if (asf) { (<Asf.Tag> adf).setDescriptorStrings(moods, "WM/Mood", "Mood"); }
     *
     *     ape = file.getTag(TagTypes.Ape);
     *     if (ape) { (<Ape.Tag>).setValue("MOOD", moods); }
     * ```
     */
    abstract getTag(types: TagTypes, create: boolean): Tag;
    /**
     * Inserts a specified block of data into the file represented by the current instance, at a
     * specified location, replacing a specified number of bytes.
     * @param data Data to insert into the file.
     * @param start Index into the file at which to insert the data. Must be safe positive integer.
     * @param replace Number of bytes to replace. Typically, this is the original size of the data
     *     block so that a new block will replace the old one.
     * @throws Error Thrown when: 1) data is falsey, 2) start is not a safe, positive number, or 3)
     *     replace is not a safe, positive number
     */
    insert(data: ByteVector, start: number, replace?: number): void;
    /**
     * Mark the current instance as corrupt. NOTE: Not intended to be used outside of this library.
     * @param reason Reason why this file is considered to be corrupt
     */
    markAsCorrupt(reason: string): void;
    /**
     * Reads a specified number of bytes at the current seek position from the current position.
     * This method reads the block of data at the current seek position. To change the seek
     * position, use {@link File.seek}.
     * @param length Number of bytes to read.
     * @returns Object containing the data read from the current instance.
     * @throws Error Thrown when `length` is not a positive, safe integer.
     */
    readBlock(length: number): ByteVector;
    /**
     * Removes a specified block of data from the file represented by the current instance.
     * @param start Index into the file at which to remove data. Must be safe, positive integer.
     * @param length Number of bytes to remove. Must be a safe integer.
     * @throws Error thrown if 1) start is not a safe, positive integer or 2) length must be a safe
     *     integer.
     */
    removeBlock(start: number, length: number): void;
    /**
     * Removes a set of tag types from the current instance. In order to remove all tags from a
     * file, pass {@link TagTypes.AllTags} as `types`
     * @param types Bitwise combined {@link TagTypes} value containing the tag types to be removed
     *     from the file
     */
    abstract removeTags(types: TagTypes): void;
    /**
     * Searches backwards through a file for a specified pattern, starting at a specified offset.
     * @param pattern Pattern to search for in the current instance. Must be shorter than the
     *     {@link bufferSize}
     * @param startPosition Number of bytes from end of the file to begin searching.
     * @throws Error Thrown if `pattern` was not provided or if `startPosition` is
     *     not a safe, positive integer.
     * @returns Index at which the value wa found. If not found, `-1` is returned.
     */
    rFind(pattern: ByteVector, startPosition?: number): number;
    /**
     * Saves the changes made in the current instance to the file it represents.
     */
    abstract save(): void;
    /**
     * Moves the read/write pointer to a specified offset in the current instance, relative to a
     * specified origin.
     * @param offset Byte offset to seek to. Must be a safe, positive integer.
     * @param origin Origin from which to seek
     */
    seek(offset: number, origin?: SeekOrigin): void;
    /**
     * Writes a block of data to the file represented by the current instance at the current seek
     * position. This will overwrite any existing data at the seek position and append new data to
     * the file if writing past the current end.
     * @param data ByteVector containing data to the current instance.
     * @throws Error Thrown when `data` is not provided.
     */
    writeBlock(data: ByteVector): void;
    /**
     * Prepares to save the file. This must be called at the beginning of every File.save() method.
     */
    protected preSave(): void;
    /**
     * Resizes the current instance to a specific number of bytes.
     * @param length Number of bytes to resize the file to, must be a safe, positive integer.
     */
    protected truncate(length: number): void;
}