midpstorage.h

来自「This is a resource based on j2me embedde」· C头文件 代码 · 共 454 行 · 第 1/2 页

/*
 *
 *
 * Copyright  1990-2007 Sun Microsystems, Inc. All Rights Reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
 * 
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License version
 * 2 only, as published by the Free Software Foundation.
 * 
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * General Public License version 2 for more details (a copy is
 * included at /legal/license.txt).
 * 
 * You should have received a copy of the GNU General Public License
 * version 2 along with this work; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA
 * 
 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
 * Clara, CA 95054 or visit www.sun.com if you need additional
 * information or have any questions.
 */

/**
 * @file
 * @brief Interface for managing persistent storage
 *
 * <p>The native-storage module hides any directory hierarchies by
 * making the file system look like a flat file system.</p>
 *
 * <p>Internal Java platform classes prefix all file names with a storage-root
 * string, and do not use directory separators. RMS adds a suite-unique string
 * to the storage-root string, also without using file separators.</p>
 *
 * <p>For filenames, the storage implementation must
 * support 255 character long, 8-bit character, file names. Legal characters
 * are A-Z, a-z, 0-9, _, %, and #.  The filenames will differ in more than
 * just case, so case-insensitive systems like Win32 are not a problem.</p>
 *
 * <p>The I/O modes for opening files are defined in the classes
 * <nobr><tt>javax.microedition.io.Connector.java</tt></nobr> and
 * <nobr><tt>com.sun.midp.io.j2me.storage.RandomAccessStream</tt></nobr>.</p>
 */

#ifndef _MIDPSTORAGE_H_
#define _MIDPSTORAGE_H_

#include <midpString.h>
#include <java_types.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Maximum length of a file name, not including the terminator.
 */
#define MAX_FILENAME_LENGTH 255 /* does not include the zero terminator */

/* I/O Modes */
/**
 * Open the file for reading only.
 */
#define OPEN_READ (1)

/**
 * Open the file for writing only; create the file if it does not
 * exist.
 */
#define OPEN_WRITE (2)

/**
 * Open the file for reading and writing; create the file if it does
 * not exist.
 */
#define OPEN_READ_WRITE (OPEN_READ|OPEN_WRITE)

/**
 * Open the file for reading and writing, creating it if it does not
 * exist and truncating it to 0 bytes if it does exist.
 */
#define OPEN_READ_WRITE_TRUNCATE (-OPEN_READ_WRITE)

/* Common file stat tests */
#ifndef S_ISREG

/**
 * file is regular flag
 */
#define S_ISREG(mode)   ( ((mode) & S_IFMT) == S_IFREG )

/**
 * special character flag
 */
#define S_ISCHR(mode)   ( ((mode) & S_IFMT) == S_IFCHR )

/**
 * fifo stream flag
 */
#define S_ISFIFO(mode)  ( ((mode) & S_IFMT) == S_ISFIFO )

/**
 * directory flag
 */
#define S_ISDIR(mode)   ( ((mode) & S_IFMT) == S_IFDIR )

/**
 * blocking flag
 */
#define S_ISBLK(mode)   ( ((mode) & S_IFMT) == S_IFBLK )
#endif /* _S_ISREG */

/** Type definition for the storage identifier */
typedef jint StorageIdType;

/**
 * Initializes the storage subsystem.
 *
 * @param midp_config pathname in the file-system where MIDP is installed
 * @param midp_home file system path to where MIDP should store its
 * data like suites and such
 *
 * @return 0 for success, or non-zero if the MIDP implementation is
 * out of memory
 */
int storageInitialize(char *midp_config, char * midp_home);

/**
 * Takes any actions necessary to safely terminate the storage
 * subsystem.
 */
void storageFinalize();

/**
 * Sets the amount of total storage space allocated to MIDlet suites to the
 * given number of bytes. The given value may be different from the system
 * default.  This value is used to enforce a maximum size limit for the
 * amount of space that can be used by installed MIDlet suites and
 * their record stores.
 *
 * <p>Do not call this function from <tt>storageInitialize</tt> if you
 * get this function's parameter value from the configuration
 * system. The configuration system cannot be used until
 * <tt>storageInitialize</tt> returns.
 *
 * @param space total amount of file space allocated to MIDP, in bytes
 */
void storageSetTotalSpace(long space);

/**
 * Returns the file separator as a string.
 *
 * <p><b>Note:</b> This function is only called by the <tt>main</tt> function
 * to manage files outside of the simulated storage area.
 *
 * @return the system-specific file separator
 */
jchar storageGetFileSeparator();

/**
 * Returns the class-path separator as a string.
 *
 * <p><b>Note:</b> This function is only called by the <tt>main</tt> function
 * to build a class path.
 *
 * @return the system-specific class-path separator
 */
jchar storageGetPathSeparator();

/**
 * Returns root string that all files should begin with, including
 * a trailing file separator if needed. By including the any trailing file
 * separators the Java API does not need to know about file separators
 * or subdirectories.
 *
 * Since the lifetime of the returned object is from storageInitialize
 * until storageFinalize, you do not have to free the returned object.
 *
 * @param storageId ID of the storage the root of which must be returned
 *
 * @return prefix used for all file names in the given storage.
 *         It may be empty, but not PCSL_STRING_NULL.
 */
const pcsl_string* storage_get_root(StorageIdType storageId);

/**
 * Returns the root string that configuration files start with, including a
 * trailing file separator when necessary. If the string includes a trailing
 * file separator, callers do not need access to file separators or
 * subdirectories.
 *
 * Since the lifetime of the returned object is from initializeConfigRoot
 * until storageFinalize, you do not have to free the returned object.
 *
 * @param storageId ID of the storage the config root of which must be returned
 *
 * @return prefix used for all configuration file names. It may be empty,
 *         but not PCSL_STRING_NULL
 */
const pcsl_string* storage_get_config_root(StorageIdType storageId);

/**
 * Frees an error string, or does nothing if null is passed in. The
 * string is expected to have been returned from a storage function.
 * This function allows for systems that provide error messages that
 * are dynamically allocated.
 *
 * @param ppszError pointer to a string that will hold an error message
 *        if there is a problem, or null if the function is
 *        successful (This function sets <tt>ppszError</tt>'s value.)
 */
void storageFreeError(char* pszError);

/**
 * Opens a native-storage file with the given name in the given mode.
 *
 * @param ppszError pointer to a string that will hold an error message
 *        if there is a problem, or null if the function is
 *        successful (This function sets <tt>ppszError</tt>'s value.)
 * @param filename the name of the file to open
 * @param ioMode the mode in which to open the file (The I/O mode
 *        constants are defined in this file.)
 *
 * @return a platform-specific handle to the open file