1/*******************************************************************************
2 * Copyright 2011 See AUTHORS file.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *   http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 ******************************************************************************/
16
17package com.badlogic.gdx;
18
19import com.badlogic.gdx.files.FileHandle;
20import com.badlogic.gdx.utils.GdxRuntimeException;
21
22/** Provides standard access to the filesystem, classpath, Android SD card, and Android assets directory.
23 * @author mzechner
24 * @author Nathan Sweet */
25public interface Files {
26	/** Indicates how to resolve a path to a file.
27	 * @author mzechner
28	 * @author Nathan Sweet */
29	public enum FileType {
30		/** Path relative to the root of the classpath. Classpath files are always readonly. Note that classpath files are not
31		 * compatible with some functionality on Android, such as {@link Audio#newSound(FileHandle)} and
32		 * {@link Audio#newMusic(FileHandle)}. */
33		Classpath,
34
35		/** Path relative to the asset directory on Android and to the application's root directory on the desktop. On the desktop,
36		 * if the file is not found, then the classpath is checked. This enables files to be found when using JWS or applets.
37		 * Internal files are always readonly. */
38		Internal,
39
40		/** Path relative to the root of the SD card on Android and to the home directory of the current user on the desktop. */
41		External,
42
43		/** Path that is a fully qualified, absolute filesystem path. To ensure portability across platforms use absolute files only
44		 * when absolutely (heh) necessary. */
45		Absolute,
46
47		/** Path relative to the private files directory on Android and to the application's root directory on the desktop. */
48		Local;
49	}
50
51	/** Returns a handle representing a file or directory.
52	 * @param type Determines how the path is resolved.
53	 * @throws GdxRuntimeException if the type is classpath or internal and the file does not exist.
54	 * @see FileType */
55	public FileHandle getFileHandle (String path, FileType type);
56
57	/** Convenience method that returns a {@link FileType#Classpath} file handle. */
58	public FileHandle classpath (String path);
59
60	/** Convenience method that returns a {@link FileType#Internal} file handle. */
61	public FileHandle internal (String path);
62
63	/** Convenience method that returns a {@link FileType#External} file handle. */
64	public FileHandle external (String path);
65
66	/** Convenience method that returns a {@link FileType#Absolute} file handle. */
67	public FileHandle absolute (String path);
68
69	/** Convenience method that returns a {@link FileType#Local} file handle. */
70	public FileHandle local (String path);
71
72	/** Returns the external storage path directory. This is the SD card on Android and the home directory of the current user on
73	 * the desktop. */
74	public String getExternalStoragePath ();
75
76	/** Returns true if the external storage is ready for file IO. Eg, on Android, the SD card is not available when mounted for use
77	 * with a PC. */
78	public boolean isExternalStorageAvailable ();
79
80	/** Returns the local storage path directory. This is the private files directory on Android and the directory of the jar on the
81	 * desktop. */
82	public String getLocalStoragePath ();
83
84	/** Returns true if the local storage is ready for file IO. */
85	public boolean isLocalStorageAvailable ();
86}
87