midpstorage.h

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

 */
int storage_open(char** ppszError, const pcsl_string* filename, int ioMode);

/**
 * Closes a native-storage file opened by storage_open.
 *
 * @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 handle handle to the open file
 */
void storageClose(char** ppszError, int handle);

/**
 * Reads from the given open native-storage file, and places the
 * results in the given buffer.
 *
 * @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 handle handle to the open file
 * @param buffer array to hold the information read (This function
 *        sets buffer's value.)
 * @param length of the given bytes array
 *
 * @return the number of bytes read (which could be fewer than the bytes
 * available in the given buffer), or -1 if there were no bytes to be read in
 * the native-storage file
 */
long storageRead(char** ppszError, int handle, char* buffer, long length);

/**
 * Writes to the given open native-storage file.  This function is
 * atomic: it will write all or none of the given bytes. If it writes
 * none, it will pass back an error in the given string pointer.
 *
 * @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 handle handle to the open native-storage file
 * @param buffer array of characters to write into storage
 * @param length the number of bytes to write (the length of buffer)
 */
void storageWrite(char** ppszError, int handle, char* buffer, long length);

/**
 * Commits or flushes pending writes to the file system.
 *
 * @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 handle handle to the open native-storage file
 */
void storageCommitWrite(char** ppszError, int handle);

/**
 * Changes the read/write position in the given open native-storage
 * file to the given position.
 *
 * @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 handle handle to the open native-storage file
 * @param absolutePosition position to move the current-position pointer to
 *        in bytes, counting from the beginning of the native-storage file
 */
void storagePosition(char** ppszError, int handle, long absolutePosition);

/**
 * Changes the read/write position in the given open native-storage
 * file by the given number of bytes.
 *
 * @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 handle handle to the open native-storage file
 * @param offset number of bytes to move the current-position pointer,
 *        counting from the pointer's current position in the
 *        native-storage file
 *
 * @return the new absolute read/write position
 */
long storageRelativePosition(char** ppszError, int handle, long offset);

/**
 * Returns the size of the given open native-storage file.
 *
 * @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 handle handle to the open native-storage file
 *
 * @return the size, in bytes, of the given open native-storage file,
 * or 0 if there was an error (for example, if the given handle was
 * not valid)
 */
long storageSizeOf(char** ppszError, int handle);

/*
 * Return the size of file with the given name in storage.
 *
 * If not successful *ppszError will set to point to an error string,
 * on success it will be set to NULL.
 *
 * @return size of file in bytes if successful, -1 otherwise
 */
long storage_size_of_file_by_name(char** ppszError,
                                  const pcsl_string* pFileName);

/**
 * Truncates the size of the given open native-storage file to the
 * given number of bytes.
 *
 * @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 handle handle to the open native-storage file
 * @param size new size of the file, in bytes
 */
void storageTruncate(char** ppszError, int handle, long size);

/**
 * Returns the amount of free space of native-file storage, in
 * bytes.
 *
 * @param storageId ID of the storage to check for free space
 *
 * @return the number of bytes of available free space
 */
jlong storage_get_free_space(StorageIdType storageId);

/**
 * Checks whether a native-storage file of the given name exists.
 *
 * @param filename name of the file that might exist
 *
 * @return a non-zero integer if the file exists; 0 otherwise
 */
int storage_file_exists(const pcsl_string* filename);

/**
 * Renames a native-storage file from the given current name to the given new
 * name.
 *
 * @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 oldFilename the current name of the file
 * @param newFilename the name to change the file to
 */
void storage_rename_file(char** ppszError, const pcsl_string* oldFilename,
                         const pcsl_string* newFilename);

/**
 * Deletes the given native-storage file. This function does not
 * block.
 *
 * @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 delete
 */
void storage_delete_file(char** ppszError,  const pcsl_string* filename);

/*
 * Returns the handle that represents the savedRootlength, savedDirectory
 * etc. This handle needs to be passed to storage_get_next_file_in_iterator()
 * in order to get the filename that matches with a given string. In
 * order to clean-up the memory storageCloseFileIterator() must be
 * called to close the handle properly.
 *
 *
 * Returns NULL if memory allocation fails for MidpStorageDirInfo structure
 * or root directory of the input 'string' can not be found
 *
 */
void* storage_open_file_iterator(const pcsl_string* string_str);

/*
 * Return the filename in storage that begins with a given string.
 * The order is defined by the underlying file system.
 * This function needs to be repeatedly called for all next
 * occurrents of the file that begins with a given string.
 *
 * Returns NULL_MIDP_STRING if no filename matches.
 *
 */
int storage_get_next_file_in_iterator(const pcsl_string* string_str, void* handle, pcsl_string* result_str);

/*
 * Close the handle i.e. pointer to MidpStorageDirInfo properly
 * and deallocate the memory
 *
 */
void storageCloseFileIterator(void* handle);

/**
 * Read pcsl_string from storage.
 * First read a jint with length, then read the text
 * of that length.
 *
 * @param ppszError  in the case of error, receives address of a string
 *                   describing the problem; receives NULL in the case of success
 * @param handle     handle of the file to read from
 * @param str        string to receive the text
 */
void
storage_read_utf16_string(char** ppszError, int handle, pcsl_string* str);

/**
 * Write pcsl_string to storage.
 * First write a jint with length, then the text.
 *
 * @param ppszError  in the case of error, receives address of a string
 *                   describing the problem
 * @param handle     handle of the file to write to
 * @param str        string to be written
 */
void
storage_write_utf16_string(char** ppszError, int handle, const pcsl_string* str);

#ifdef __cplusplus
}
#endif

#endif /* _MIDPSTORAGE_H_ */