ShuriZma
/
visualboyadvance-m
mirror of https://github.com/visualboyadvance-m/visualboyadvance-m.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

SVN: Set more properties

This commit is contained in:
bgk 2011-02-20 19:06:05 +00:00
parent b213ae372b
commit 000f563d59
9 changed files with 1949 additions and 1949 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

156
CMakeScripts/FindSFML.cmake
View File

@ -1,78 +1,78 @@
# Locate SFML library
# This module defines
# SFML_LIBRARY, the name of the library to link against
# SFML_FOUND, if false, do not try to link to SFML
# SFML_INCLUDE_DIR, where to find SFML headers
#
# Created by Nils Hasenbanck. Based on the FindSDL_*.cmake modules,
# created by Eric Wing, which were influenced by the FindSDL.cmake
# module, but with modifications to recognize OS X frameworks and
# additional Unix paths (FreeBSD, etc).
SET(SFML_COMPONENTS
System
Audio
Graphics
Network
Window
)
SET(SFML_INCLUDE_SEARCH_DIR
~/Library/Frameworks
/Library/Frameworks
/usr/local/include/SFML
/usr/include/SFML
/usr/local/include
/usr/include
/sw/include/SFML # Fink
/sw/include
/opt/local/include/SFML # DarwinPorts
/opt/local/include
/opt/csw/include/SFML # Blastwave
/opt/csw/include
/opt/include/SFML
/opt/include
)
SET(SFML_LIBRARY_SEARCH_DIR
~/Library/Frameworks
/Library/Frameworks
/usr/local
/usr
/sw
/opt/local
/opt/csw
/opt
)
FOREACH(COMPONENT ${SFML_COMPONENTS})
STRING(TOUPPER ${COMPONENT} UPPERCOMPONENT)
STRING(TOLOWER ${COMPONENT} LOWERCOMPONENT)
FIND_LIBRARY(SFML_${UPPERCOMPONENT}_LIBRARY
NAMES sfml-${LOWERCOMPONENT}
HINTS
$ENV{SFMLDIR}
PATH_SUFFIXES lib64 lib
PATHS ${SFML_LIBRARY_SEARCH_DIR}
)
FIND_PATH(SFML_${UPPERCOMPONENT}_INCLUDE_DIR ${COMPONENT}.hpp
HINTS
$ENV{SFMLDIR}
PATH_SUFFIXES include
PATHS ${SFML_INCLUDE_SEARCH_DIR}
)
IF(SFML_${UPPERCOMPONENT}_INCLUDE_DIR AND SFML_${UPPERCOMPONENT}_LIBRARY)
LIST(APPEND SFML_LIBRARY ${SFML_${UPPERCOMPONENT}_LIBRARY})
LIST(APPEND SFML_INCLUDE_DIR ${SFML_${UPPERCOMPONENT}_INCLUDE_DIR})
LIST(REMOVE_DUPLICATES SFML_LIBRARY)
LIST(REMOVE_DUPLICATES SFML_INCLUDE_DIR)
ENDIF(SFML_${UPPERCOMPONENT}_INCLUDE_DIR AND SFML_${UPPERCOMPONENT}_LIBRARY)
ENDFOREACH(COMPONENT)
SET(SFML_FOUND "NO")
IF(SFML_SYSTEM_LIBRARY AND SFML_INCLUDE_DIR)
SET(SFML_FOUND "YES")
ENDIF(SFML_SYSTEM_LIBRARY AND SFML_INCLUDE_DIR)
INCLUDE(FindPackageHandleStandardArgs)
FIND_PACKAGE_HANDLE_STANDARD_ARGS(SFML DEFAULT_MSG SFML_LIBRARY SFML_INCLUDE_DIR)
# Locate SFML library
# This module defines
# SFML_LIBRARY, the name of the library to link against
# SFML_FOUND, if false, do not try to link to SFML
# SFML_INCLUDE_DIR, where to find SFML headers
#
# Created by Nils Hasenbanck. Based on the FindSDL_*.cmake modules,
# created by Eric Wing, which were influenced by the FindSDL.cmake
# module, but with modifications to recognize OS X frameworks and
# additional Unix paths (FreeBSD, etc).
SET(SFML_COMPONENTS
System
Audio
Graphics
Network
Window
)
SET(SFML_INCLUDE_SEARCH_DIR
~/Library/Frameworks
/Library/Frameworks
/usr/local/include/SFML
/usr/include/SFML
/usr/local/include
/usr/include
/sw/include/SFML # Fink
/sw/include
/opt/local/include/SFML # DarwinPorts
/opt/local/include
/opt/csw/include/SFML # Blastwave
/opt/csw/include
/opt/include/SFML
/opt/include
)
SET(SFML_LIBRARY_SEARCH_DIR
~/Library/Frameworks
/Library/Frameworks
/usr/local
/usr
/sw
/opt/local
/opt/csw
/opt
)
FOREACH(COMPONENT ${SFML_COMPONENTS})
STRING(TOUPPER ${COMPONENT} UPPERCOMPONENT)
STRING(TOLOWER ${COMPONENT} LOWERCOMPONENT)
FIND_LIBRARY(SFML_${UPPERCOMPONENT}_LIBRARY
NAMES sfml-${LOWERCOMPONENT}
HINTS
$ENV{SFMLDIR}
PATH_SUFFIXES lib64 lib
PATHS ${SFML_LIBRARY_SEARCH_DIR}
)
FIND_PATH(SFML_${UPPERCOMPONENT}_INCLUDE_DIR ${COMPONENT}.hpp
HINTS
$ENV{SFMLDIR}
PATH_SUFFIXES include
PATHS ${SFML_INCLUDE_SEARCH_DIR}
)
IF(SFML_${UPPERCOMPONENT}_INCLUDE_DIR AND SFML_${UPPERCOMPONENT}_LIBRARY)
LIST(APPEND SFML_LIBRARY ${SFML_${UPPERCOMPONENT}_LIBRARY})
LIST(APPEND SFML_INCLUDE_DIR ${SFML_${UPPERCOMPONENT}_INCLUDE_DIR})
LIST(REMOVE_DUPLICATES SFML_LIBRARY)
LIST(REMOVE_DUPLICATES SFML_INCLUDE_DIR)
ENDIF(SFML_${UPPERCOMPONENT}_INCLUDE_DIR AND SFML_${UPPERCOMPONENT}_LIBRARY)
ENDFOREACH(COMPONENT)
SET(SFML_FOUND "NO")
IF(SFML_SYSTEM_LIBRARY AND SFML_INCLUDE_DIR)
SET(SFML_FOUND "YES")
ENDIF(SFML_SYSTEM_LIBRARY AND SFML_INCLUDE_DIR)
INCLUDE(FindPackageHandleStandardArgs)
FIND_PACKAGE_HANDLE_STANDARD_ARGS(SFML DEFAULT_MSG SFML_LIBRARY SFML_INCLUDE_DIR)

56
doc/License.txt
View File

@ -1,28 +1,28 @@
Copyright for all files in trunk/src excluding gb_apu
or when stated otherwise in the source file:
VisualBoyAdvance - Nintendo Gameboy/GameboyAdvance (TM) emulator
Copyright (C) 1999-2003 Forgotten
Copyright (C) 2004-2006 Forgotten and the VBA development team
Copyright for the modifications to the files mentioned above:
VisualBoyAdvance-M GB/GBA emulator
Copyright (C) 2007-2008 VBA-M development team
All files excluding gb_apu, modified files from zlib
or when stated otherwise in the source file
are distributed under the GNU GPL v2:
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or(at your option)
any later version.
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 for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software Foundation,
Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
Copyright for all files in trunk/src excluding gb_apu
or when stated otherwise in the source file:
VisualBoyAdvance - Nintendo Gameboy/GameboyAdvance (TM) emulator
Copyright (C) 1999-2003 Forgotten
Copyright (C) 2004-2006 Forgotten and the VBA development team
Copyright for the modifications to the files mentioned above:
VisualBoyAdvance-M GB/GBA emulator
Copyright (C) 2007-2008 VBA-M development team
All files excluding gb_apu, modified files from zlib
or when stated otherwise in the source file
are distributed under the GNU GPL v2:
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or(at your option)
any later version.
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 for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software Foundation,
Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

388
fex/7z_C/7zC.txt
View File

@ -1,194 +1,194 @@
7z ANSI-C Decoder 4.62
----------------------
7z ANSI-C provides 7z/LZMA decoding.
7z ANSI-C version is simplified version ported from C++ code.
LZMA is default and general compression method of 7z format
in 7-Zip compression program (www.7-zip.org). LZMA provides high
compression ratio and very fast decompression.
LICENSE
-------
7z ANSI-C Decoder is part of the LZMA SDK.
LZMA SDK is written and placed in the public domain by Igor Pavlov.
Files
---------------------
7zDecode.* - Low level 7z decoding
7zExtract.* - High level 7z decoding
7zHeader.* - .7z format constants
7zIn.* - .7z archive opening
7zItem.* - .7z structures
7zMain.c - Test application
How To Use
----------
You must download 7-Zip program from www.7-zip.org.
You can create .7z archive with 7z.exe or 7za.exe:
7za.exe a archive.7z *.htm -r -mx -m0fb=255
If you have big number of files in archive, and you need fast extracting,
you can use partly-solid archives:
7za.exe a archive.7z *.htm -ms=512K -r -mx -m0fb=255 -m0d=512K
In that example 7-Zip will use 512KB solid blocks. So it needs to decompress only
512KB for extracting one file from such archive.
Limitations of current version of 7z ANSI-C Decoder
---------------------------------------------------
- It reads only "FileName", "Size", "LastWriteTime" and "CRC" information for each file in archive.
- It supports only LZMA and Copy (no compression) methods with BCJ or BCJ2 filters.
- It converts original UTF-16 Unicode file names to UTF-8 Unicode file names.
These limitations will be fixed in future versions.
Using 7z ANSI-C Decoder Test application:
-----------------------------------------
Usage: 7zDec <command> <archive_name>
<Command>:
e: Extract files from archive
l: List contents of archive
t: Test integrity of archive
Example:
7zDec l archive.7z
lists contents of archive.7z
7zDec e archive.7z
extracts files from archive.7z to current folder.
How to use .7z Decoder
----------------------
Memory allocation
~~~~~~~~~~~~~~~~~
7z Decoder uses two memory pools:
1) Temporary pool
2) Main pool
Such scheme can allow you to avoid fragmentation of allocated blocks.
Steps for using 7z decoder
--------------------------
Use code at 7zMain.c as example.
1) Declare variables:
inStream /* implements ILookInStream interface */
CSzArEx db; /* 7z archive database structure */
ISzAlloc allocImp; /* memory functions for main pool */
ISzAlloc allocTempImp; /* memory functions for temporary pool */
2) call CrcGenerateTable(); function to initialize CRC structures.
3) call SzArEx_Init(&db); function to initialize db structures.
4) call SzArEx_Open(&db, inStream, &allocMain, &allocTemp) to open archive
This function opens archive "inStream" and reads headers to "db".
All items in "db" will be allocated with "allocMain" functions.
SzArEx_Open function allocates and frees temporary structures by "allocTemp" functions.
5) List items or Extract items
Listing code:
~~~~~~~~~~~~~
{
UInt32 i;
for (i = 0; i < db.db.NumFiles; i++)
{
CFileItem *f = db.db.Files + i;
printf("%10d %s\n", (int)f->Size, f->Name);
}
}
Extracting code:
~~~~~~~~~~~~~~~~
SZ_RESULT SzAr_Extract(
CArchiveDatabaseEx *db,
ILookInStream *inStream,
UInt32 fileIndex, /* index of file */
UInt32 *blockIndex, /* index of solid block */
Byte **outBuffer, /* pointer to pointer to output buffer (allocated with allocMain) */
size_t *outBufferSize, /* buffer size for output buffer */
size_t *offset, /* offset of stream for required file in *outBuffer */
size_t *outSizeProcessed, /* size of file in *outBuffer */
ISzAlloc *allocMain,
ISzAlloc *allocTemp);
If you need to decompress more than one file, you can send these values from previous call:
blockIndex,
outBuffer,
outBufferSize,
You can consider "outBuffer" as cache of solid block. If your archive is solid,
it will increase decompression speed.
After decompressing you must free "outBuffer":
allocImp.Free(outBuffer);
6) call SzArEx_Free(&db, allocImp.Free) to free allocated items in "db".
Memory requirements for .7z decoding
------------------------------------
Memory usage for Archive opening:
- Temporary pool:
- Memory for uncompressed .7z headers
- some other temporary blocks
- Main pool:
- Memory for database:
Estimated size of one file structures in solid archive:
- Size (4 or 8 Bytes)
- CRC32 (4 bytes)
- LastWriteTime (8 bytes)
- Some file information (4 bytes)
- File Name (variable length) + pointer + allocation structures
Memory usage for archive Decompressing:
- Temporary pool:
- Memory for LZMA decompressing structures
- Main pool:
- Memory for decompressed solid block
- Memory for temprorary buffers, if BCJ2 fileter is used. Usually these
temprorary buffers can be about 15% of solid block size.
7z Decoder doesn't allocate memory for compressed blocks.
Instead of this, you must allocate buffer with desired
size before calling 7z Decoder. Use 7zMain.c as example.
Defines
-------
_SZ_ALLOC_DEBUG - define it if you want to debug alloc/free operations to stderr.
---
http://www.7-zip.org
http://www.7-zip.org/sdk.html
http://www.7-zip.org/support.html
7z ANSI-C Decoder 4.62
----------------------
7z ANSI-C provides 7z/LZMA decoding.
7z ANSI-C version is simplified version ported from C++ code.
LZMA is default and general compression method of 7z format
in 7-Zip compression program (www.7-zip.org). LZMA provides high
compression ratio and very fast decompression.
LICENSE
-------
7z ANSI-C Decoder is part of the LZMA SDK.
LZMA SDK is written and placed in the public domain by Igor Pavlov.
Files
---------------------
7zDecode.* - Low level 7z decoding
7zExtract.* - High level 7z decoding
7zHeader.* - .7z format constants
7zIn.* - .7z archive opening
7zItem.* - .7z structures
7zMain.c - Test application
How To Use
----------
You must download 7-Zip program from www.7-zip.org.
You can create .7z archive with 7z.exe or 7za.exe:
7za.exe a archive.7z *.htm -r -mx -m0fb=255
If you have big number of files in archive, and you need fast extracting,
you can use partly-solid archives:
7za.exe a archive.7z *.htm -ms=512K -r -mx -m0fb=255 -m0d=512K
In that example 7-Zip will use 512KB solid blocks. So it needs to decompress only
512KB for extracting one file from such archive.
Limitations of current version of 7z ANSI-C Decoder
---------------------------------------------------
- It reads only "FileName", "Size", "LastWriteTime" and "CRC" information for each file in archive.
- It supports only LZMA and Copy (no compression) methods with BCJ or BCJ2 filters.
- It converts original UTF-16 Unicode file names to UTF-8 Unicode file names.
These limitations will be fixed in future versions.
Using 7z ANSI-C Decoder Test application:
-----------------------------------------
Usage: 7zDec <command> <archive_name>
<Command>:
e: Extract files from archive
l: List contents of archive
t: Test integrity of archive
Example:
7zDec l archive.7z
lists contents of archive.7z
7zDec e archive.7z
extracts files from archive.7z to current folder.
How to use .7z Decoder
----------------------
Memory allocation
~~~~~~~~~~~~~~~~~
7z Decoder uses two memory pools:
1) Temporary pool
2) Main pool
Such scheme can allow you to avoid fragmentation of allocated blocks.
Steps for using 7z decoder
--------------------------
Use code at 7zMain.c as example.
1) Declare variables:
inStream /* implements ILookInStream interface */
CSzArEx db; /* 7z archive database structure */
ISzAlloc allocImp; /* memory functions for main pool */
ISzAlloc allocTempImp; /* memory functions for temporary pool */
2) call CrcGenerateTable(); function to initialize CRC structures.
3) call SzArEx_Init(&db); function to initialize db structures.
4) call SzArEx_Open(&db, inStream, &allocMain, &allocTemp) to open archive
This function opens archive "inStream" and reads headers to "db".
All items in "db" will be allocated with "allocMain" functions.
SzArEx_Open function allocates and frees temporary structures by "allocTemp" functions.
5) List items or Extract items
Listing code:
~~~~~~~~~~~~~
{
UInt32 i;
for (i = 0; i < db.db.NumFiles; i++)
{
CFileItem *f = db.db.Files + i;
printf("%10d %s\n", (int)f->Size, f->Name);
}
}
Extracting code:
~~~~~~~~~~~~~~~~
SZ_RESULT SzAr_Extract(
CArchiveDatabaseEx *db,
ILookInStream *inStream,
UInt32 fileIndex, /* index of file */
UInt32 *blockIndex, /* index of solid block */
Byte **outBuffer, /* pointer to pointer to output buffer (allocated with allocMain) */
size_t *outBufferSize, /* buffer size for output buffer */
size_t *offset, /* offset of stream for required file in *outBuffer */
size_t *outSizeProcessed, /* size of file in *outBuffer */
ISzAlloc *allocMain,
ISzAlloc *allocTemp);
If you need to decompress more than one file, you can send these values from previous call:
blockIndex,
outBuffer,
outBufferSize,
You can consider "outBuffer" as cache of solid block. If your archive is solid,
it will increase decompression speed.
After decompressing you must free "outBuffer":
allocImp.Free(outBuffer);
6) call SzArEx_Free(&db, allocImp.Free) to free allocated items in "db".
Memory requirements for .7z decoding
------------------------------------
Memory usage for Archive opening:
- Temporary pool:
- Memory for uncompressed .7z headers
- some other temporary blocks
- Main pool:
- Memory for database:
Estimated size of one file structures in solid archive:
- Size (4 or 8 Bytes)
- CRC32 (4 bytes)
- LastWriteTime (8 bytes)
- Some file information (4 bytes)
- File Name (variable length) + pointer + allocation structures
Memory usage for archive Decompressing:
- Temporary pool:
- Memory for LZMA decompressing structures
- Main pool:
- Memory for decompressed solid block
- Memory for temprorary buffers, if BCJ2 fileter is used. Usually these
temprorary buffers can be about 15% of solid block size.
7z Decoder doesn't allocate memory for compressed blocks.
Instead of this, you must allocate buffer with desired
size before calling 7z Decoder. Use 7zMain.c as example.
Defines
-------
_SZ_ALLOC_DEBUG - define it if you want to debug alloc/free operations to stderr.
---
http://www.7-zip.org
http://www.7-zip.org/sdk.html
http://www.7-zip.org/support.html

1188
fex/7z_C/lzma.txt
View File

File diff suppressed because it is too large Load Diff

142
fex/changes.txt
View File

@ -1,71 +1,71 @@
File_Extractor Change Log
-------------------------
- Change that might break code.
+ Improvement that is unlikely to break any code.
* Other changes.
File_Extractor 1.0.0 (2009-10-12)
--------------------
- Added fex_stat() which MUST be called before getting current file
information beyond name, like fex_size().
- Changed fex_*() functions to always report error via return value,
rather than sometimes via a parameter. This will break user code that
uses fex_data(), fex_open(), fex_open_type(), and fex_identify_file().
See demos for usage.
- Deprecated C++ interface. Use fex.h and nothing else to access library
from user code.
- Removed archive types (fex_zip_type, etc.) from interface. Use
fex_identify_extension() to get particular type.
- Removed fex_mini.c, unzip.h, and unrarlib.h for now, as maintaining
them was too taxing. If others express desire for them, I can re-add
them.
- Removed fex_scan_only() and fex_read_once(), as they don't improve
performance anymore. Use fex_read() in place of fex_read_once().
- Removed fex_remain(). Use fex_size()-fex_tell() to find number of
bytes remaining.
- Removed fex_set_user_data() and related functions, as they didn't seem
useful to anyone.
- Removed fex_type_t structure from interface and added accessors
instead (fex_type_name(), fex_type_extension()).
+ Improved archive file type determination to reject other archive types
not handled by the library, rather than opening them as binary files.
+ Added Doxygen compatibility to fex.h.
+ Added fex_crc32() to quickly get CRC-32 of current file from archive
header, without having to read entire file to calculate it.
+ Added fex_err_code() to get numeric error code, along with other
helpful error-related functions. Also added more documentation on how to
handle library errors in user code.
+ Added fex_init() for use in multi-threaded programs.
+ Added fex_seek_arc() to seek to particular file in archive.
+ Added fex_wname() to get Unicode name of current file.
+ Added support for building as DLL.
+ Added support for wide-character file paths on Windows, enabled with
BLARGG_UTF8_PATHS (thanks to byuu for the idea). This is necessary to
support file paths on non-English Windows systems.
+ Started using unit testing during development.
+ Updated to 7-zip 4.65, unrar_core 3.8.5.
File_Extractor 0.4.3 (2008-12-08)
--------------------
* Limited release
File_Extractor Change Log
-------------------------
- Change that might break code.
+ Improvement that is unlikely to break any code.
* Other changes.
File_Extractor 1.0.0 (2009-10-12)
--------------------
- Added fex_stat() which MUST be called before getting current file
information beyond name, like fex_size().
- Changed fex_*() functions to always report error via return value,
rather than sometimes via a parameter. This will break user code that
uses fex_data(), fex_open(), fex_open_type(), and fex_identify_file().
See demos for usage.
- Deprecated C++ interface. Use fex.h and nothing else to access library
from user code.
- Removed archive types (fex_zip_type, etc.) from interface. Use
fex_identify_extension() to get particular type.
- Removed fex_mini.c, unzip.h, and unrarlib.h for now, as maintaining
them was too taxing. If others express desire for them, I can re-add
them.
- Removed fex_scan_only() and fex_read_once(), as they don't improve
performance anymore. Use fex_read() in place of fex_read_once().
- Removed fex_remain(). Use fex_size()-fex_tell() to find number of
bytes remaining.
- Removed fex_set_user_data() and related functions, as they didn't seem
useful to anyone.
- Removed fex_type_t structure from interface and added accessors
instead (fex_type_name(), fex_type_extension()).
+ Improved archive file type determination to reject other archive types
not handled by the library, rather than opening them as binary files.
+ Added Doxygen compatibility to fex.h.
+ Added fex_crc32() to quickly get CRC-32 of current file from archive
header, without having to read entire file to calculate it.
+ Added fex_err_code() to get numeric error code, along with other
helpful error-related functions. Also added more documentation on how to
handle library errors in user code.
+ Added fex_init() for use in multi-threaded programs.
+ Added fex_seek_arc() to seek to particular file in archive.
+ Added fex_wname() to get Unicode name of current file.
+ Added support for building as DLL.
+ Added support for wide-character file paths on Windows, enabled with
BLARGG_UTF8_PATHS (thanks to byuu for the idea). This is necessary to
support file paths on non-English Windows systems.
+ Started using unit testing during development.
+ Updated to 7-zip 4.65, unrar_core 3.8.5.
File_Extractor 0.4.3 (2008-12-08)
--------------------
* Limited release

660
fex/fex.txt
View File

@ -1,330 +1,330 @@
File_Extractor 1.0.0
--------------------
Author : Shay Green <gblargg@gmail.com>
Website : http://code.google.com/p/file-extractor/
License : GNU LGPL 2.1 or later for all except unrar
Language: C interface, C++ implementation
Contents
--------
* Overview
* Limitations
* Extracting file data
* Archive file type handling
* Using in multiple threads
* Error handling
* Solving problems
* Thanks
Overview
--------
File_Exactor (fex) allows you to write one version of file-opening code
that handles normal files and archives of files. It presents each as a
series of files that you can scan and optionally extract; a single file
is made to act like an archive of just one file, so your code doesn't
need to do anything special to handle it.
Basic steps for scanning and extracting from an archive:
* Open an archive or normal file using fex_open().
* Scanning/extraction loop:
- Exit loop if fex_done() returns true.
- Get current file's name with fex_name().
- If more file information is needed, call fex_stat() first.
- If extracting, use fex_data() or fex_read().
- Go to next file in archive with fex_next().
* Close archive and free memory with fex_close().
You can stop scanning an archive at any point, for example once you've
found the file you're looking for. If you need to go back to the first
file, call fex_rewind() at any time. Be sure to check error codes
returned by most functions.
Limitations
-----------
All archives:
* A file's checksum is verified only after ALL its data is extracted.
* Encryption, segmentation, files larger than 2GB, and other extra
features are not supported.
GZ archives:
* Only gzip archives of a single file are supported. If it has multiple
files, the reported size will be wrong. Multi-file gzip archives are
very rare.
ZIP archives:
* Supports files compressed using either deflation or store
(uncompressed). Other compression schemes like BZip2 and Deflate64 are
not supported.
* Archive must have a valid directory structure at the end.
RAR archives:
* Support for really old 1.x archives might not work. If you have some
of these old archives, send them to me so I can test them.
7-zip:
* Solid archives can currently use lots of memory when open.
Extracting file data
--------------------
A file's data can be extracted with one or more calls to fex_read(), as
you would read from a normal file. Use fex_tell() to find out how much
has already been read. Use this if you need the data read into your own
structure in memory.
File data can also be extracted to memory by the library with
fex_data(). The pointer returned is valid only until you go to another
file or close the archive, so this is only useful if you need to examine
or process the data immediately and not keep it around for later.
Archive extractors naturally keep a copy of the extracted data in memory
already for solid archive types (currently 7-zip and RAR), so this
function is optimized to avoid making a second copy of it in those
cases.
Use fex_size() to find the size of the extracted data. Remember that
fex_stat() or fex_data() must be called BEFORE calling fex_size().
Archive file type handling
--------------------------
By default, fex uses the filename extension and header to determine
archive type. If the filename extension is unrecognized or it lacks an
extension, fex examines the first few bytes of the file. If still
unrecognized, fex opens it as binary. Fex also checks for common archive
types that it doesn't support, so that it can reject as unsupported them
rather than unhelpfully opening them as binary.
Your file format might itself be an archive, for example your files end
in ".rsn" yet are normal RAR archives, or they end in ".vgz" and are
gzipped. This is why fex checks the headers of files with unknown
filename extensions, rather than treating them as binary or rejecting
them.
Type identification can be customized by using the various
identification functions and fex_open_type(). For example, you could
avoid the header check:
fex_t* fex;
fex_type_t type = fex_identify_extension( path );
if ( type == NULL )
error( "Unsupported archive type" );
error( fex_open_type( &fex, path, type ) );
Note that you'll only get a NULL type for known archive type that fex
doesn't handle; you won't get it for your own files, for example
fex_identify_extension("myfile.foo") won't return NULL (unless for some
reason you've disabled binary file support).
Use fex_type_list() to get a list of the types fex supports, for example
to tell the user what archive types your program supports:
const fex_type_t* t;
for ( t = fex_type_list(); *t; t++ )
printf( "%s\n", fex_type_name( *t ) );
To get the fex_type_t for a particular archive type, use
fex_identify_extension():
fex_type_t zip_type = fex_identify_extension( ".zip" );
if ( zip_type == NULL )
error( "ZIP isn't supported" );
Be sure to check the result as shown, rather than assuming the library
supports a particular archive type. Use an extension of "" to get the
type for binary files:
fex_type_t bin_type = fex_identify_extension( "" );
if ( bin_type == NULL )
error( "Binary files aren't supported?!?" );
Using in multiple threads
-------------------------
Fex supports multi-threaded programs. If only one thread at a time is
using the library, nothing special needs to be done. If more than one
thread is using the library, the following must be done:
* Call fex_init() from the main thread and ensure it completes before
any other threads use any fex functions. This initializes shared data
tables used by the extractors.
* For each archive opened, only access it from one thread at a time.
Different archives can be accessed from different threads without any
synchronization, since fex uses no global variables. If the same archive
must be accessed from multiple threads, all calls to any fex functions
must be in critical section(s).
Unicode file paths on Windows
-----------------------------
If using Windows and your program supports Unicode file paths, enable
BLARGG_UTF8_PATHS in blargg_config.h, and convert your wide-character
paths to UTF-8 before passing them to fex.h functions:
/* Wide-character path that could have come from system */
wchar_t wide_path [] = L"demo.zip";
/* Convert from wide path and check for error */
char* path = fex_wide_to_path( wide_path );
if ( path == NULL )
error( "Out of memory" );
/* Use converted path for fex call */
error( fex_open( &fex, path ) );
/* Free memory used by path */
fex_free_path( path );
The converted path can be used with any of the fex functions that take
paths, for example fex_identify_extension() or fex_has_extension().
Error handling
--------------
Most functions that can fail return fex_err_t, a pointer type. On
failure they return a pointer to an error object, and on success they
return NULL. Use fex_err_code() to get a conventional error code, or
fex_err_str() to get a string suitable for reporting to the user.
There are two basic approches that your code can use to handle library
errors. It can return errors, or report them and exit the function via
some other means.
Your code can return errors as the library does, using fex_err_t:
#define RETURN_ERR( expr ) \
do {\
fex_err_t err = (expr);\
if ( err != NULL )\
return err;\
} while ( 0 )
fex_err_t my_func()
{
RETURN_ERR( fex_foo() );
RETURN_ERR( fex_bar() );
return NULL;
}
If you have your own error codes, you can convert fex's errors to them:
// error codes that differ from library's
enum {
my_ok = 0,
my_generic_error = 123,
my_out_of_memory = 456,
my_file_not_found = 789
// ...
};
int convert_error( fex_err_t err )
{
switch ( fex_err_code( err ) )
{
case fex_ok: return my_ok;
case fex_err_generic: return my_generic_error;
case fex_err_memory: return my_out_of_memory;
case fex_err_file_missing: return my_file_not_found;
// ...
default: return my_generic_error;
}
}
#define RETURN_ERR( expr ) \
do {\
fex_err_t err = (expr);\
if ( err != NULL )\
return convert_error( err );\
} while ( 0 )
int my_func()
{
RETURN_ERR( fex_foo() );
RETURN_ERR( fex_bar() );
return my_ok;
}
The other approach is to pass all errors to an error handler function
that never returns if passed a non-success error value:
// never returns if err != NULL
void handle_error( fex_err_t err );
void my_func()
{
handle_error( fex_foo() );
handle_error( fex_bar() );
}
handle_error() could print the error and exit the program:
void handle_error( fex_err_t err )
{
if ( err != NULL )
{
const char* str = fex_err_str( err );
printf( "Error: %s\n", str );
exit( EXIT_FAILURE );
}
}
handle_error() could also throw a C++ exception (or equivalently in C,
longmp() back to a setjmp() done inside caller()):
void handle_error( fex_err_t err )
{
switch ( fex_err_code( err ) )
{
case fex_ok: return;
case fex_err_memory: throw std::bad_alloc();
// ...
case fex_err_generic:
default:
throw std::runtime_error( fex_err_str( err ) );
}
}
void caller()
{
try
{
my_func();
}
catch ( const std::exception& e )
{
printf( "Error: %s\n", e.what() );
}
}
Solving problems
----------------
If you're having problems, try the following:
* Enable debugging support in your environment. This enables assertions
and other run-time checks. In particular, be sure NDEBUG isn't defined.
* Turn the compiler's optimizer is off. Sometimes an optimizer generates
bad code.
* If multiple threads are being used, ensure that only one at a time is
accessing a given set of objects from the library. This library is not
in general thread-safe, though independent objects can be used in
separate threads.
* If all else fails, see if the demo works.
Thanks
------
Thanks to Richard Bannister, Kode54, byuu, Cless, and DJRobX for testing
and giving feedback for the library. Thanks to the authors of zlib,
unrar, and 7-zip.
--
Shay Green <gblargg@gmail.com>
File_Extractor 1.0.0
--------------------
Author : Shay Green <gblargg@gmail.com>
Website : http://code.google.com/p/file-extractor/
License : GNU LGPL 2.1 or later for all except unrar
Language: C interface, C++ implementation
Contents
--------
* Overview
* Limitations
* Extracting file data
* Archive file type handling
* Using in multiple threads
* Error handling
* Solving problems
* Thanks
Overview
--------
File_Exactor (fex) allows you to write one version of file-opening code
that handles normal files and archives of files. It presents each as a
series of files that you can scan and optionally extract; a single file
is made to act like an archive of just one file, so your code doesn't
need to do anything special to handle it.
Basic steps for scanning and extracting from an archive:
* Open an archive or normal file using fex_open().
* Scanning/extraction loop:
- Exit loop if fex_done() returns true.
- Get current file's name with fex_name().
- If more file information is needed, call fex_stat() first.
- If extracting, use fex_data() or fex_read().
- Go to next file in archive with fex_next().
* Close archive and free memory with fex_close().
You can stop scanning an archive at any point, for example once you've
found the file you're looking for. If you need to go back to the first
file, call fex_rewind() at any time. Be sure to check error codes
returned by most functions.
Limitations
-----------
All archives:
* A file's checksum is verified only after ALL its data is extracted.
* Encryption, segmentation, files larger than 2GB, and other extra
features are not supported.
GZ archives:
* Only gzip archives of a single file are supported. If it has multiple
files, the reported size will be wrong. Multi-file gzip archives are
very rare.
ZIP archives:
* Supports files compressed using either deflation or store
(uncompressed). Other compression schemes like BZip2 and Deflate64 are
not supported.
* Archive must have a valid directory structure at the end.
RAR archives:
* Support for really old 1.x archives might not work. If you have some
of these old archives, send them to me so I can test them.
7-zip:
* Solid archives can currently use lots of memory when open.
Extracting file data
--------------------
A file's data can be extracted with one or more calls to fex_read(), as
you would read from a normal file. Use fex_tell() to find out how much
has already been read. Use this if you need the data read into your own
structure in memory.
File data can also be extracted to memory by the library with
fex_data(). The pointer returned is valid only until you go to another
file or close the archive, so this is only useful if you need to examine
or process the data immediately and not keep it around for later.
Archive extractors naturally keep a copy of the extracted data in memory
already for solid archive types (currently 7-zip and RAR), so this
function is optimized to avoid making a second copy of it in those
cases.
Use fex_size() to find the size of the extracted data. Remember that
fex_stat() or fex_data() must be called BEFORE calling fex_size().
Archive file type handling
--------------------------
By default, fex uses the filename extension and header to determine
archive type. If the filename extension is unrecognized or it lacks an
extension, fex examines the first few bytes of the file. If still
unrecognized, fex opens it as binary. Fex also checks for common archive
types that it doesn't support, so that it can reject as unsupported them
rather than unhelpfully opening them as binary.
Your file format might itself be an archive, for example your files end
in ".rsn" yet are normal RAR archives, or they end in ".vgz" and are
gzipped. This is why fex checks the headers of files with unknown
filename extensions, rather than treating them as binary or rejecting
them.
Type identification can be customized by using the various
identification functions and fex_open_type(). For example, you could
avoid the header check:
fex_t* fex;
fex_type_t type = fex_identify_extension( path );
if ( type == NULL )
error( "Unsupported archive type" );
error( fex_open_type( &fex, path, type ) );
Note that you'll only get a NULL type for known archive type that fex
doesn't handle; you won't get it for your own files, for example
fex_identify_extension("myfile.foo") won't return NULL (unless for some
reason you've disabled binary file support).
Use fex_type_list() to get a list of the types fex supports, for example
to tell the user what archive types your program supports:
const fex_type_t* t;
for ( t = fex_type_list(); *t; t++ )
printf( "%s\n", fex_type_name( *t ) );
To get the fex_type_t for a particular archive type, use
fex_identify_extension():
fex_type_t zip_type = fex_identify_extension( ".zip" );
if ( zip_type == NULL )
error( "ZIP isn't supported" );
Be sure to check the result as shown, rather than assuming the library
supports a particular archive type. Use an extension of "" to get the
type for binary files:
fex_type_t bin_type = fex_identify_extension( "" );
if ( bin_type == NULL )
error( "Binary files aren't supported?!?" );
Using in multiple threads
-------------------------
Fex supports multi-threaded programs. If only one thread at a time is
using the library, nothing special needs to be done. If more than one
thread is using the library, the following must be done:
* Call fex_init() from the main thread and ensure it completes before
any other threads use any fex functions. This initializes shared data
tables used by the extractors.
* For each archive opened, only access it from one thread at a time.
Different archives can be accessed from different threads without any
synchronization, since fex uses no global variables. If the same archive
must be accessed from multiple threads, all calls to any fex functions
must be in critical section(s).
Unicode file paths on Windows
-----------------------------
If using Windows and your program supports Unicode file paths, enable
BLARGG_UTF8_PATHS in blargg_config.h, and convert your wide-character
paths to UTF-8 before passing them to fex.h functions:
/* Wide-character path that could have come from system */
wchar_t wide_path [] = L"demo.zip";
/* Convert from wide path and check for error */
char* path = fex_wide_to_path( wide_path );
if ( path == NULL )
error( "Out of memory" );
/* Use converted path for fex call */
error( fex_open( &fex, path ) );
/* Free memory used by path */
fex_free_path( path );
The converted path can be used with any of the fex functions that take
paths, for example fex_identify_extension() or fex_has_extension().
Error handling
--------------
Most functions that can fail return fex_err_t, a pointer type. On
failure they return a pointer to an error object, and on success they
return NULL. Use fex_err_code() to get a conventional error code, or
fex_err_str() to get a string suitable for reporting to the user.
There are two basic approches that your code can use to handle library
errors. It can return errors, or report them and exit the function via
some other means.
Your code can return errors as the library does, using fex_err_t:
#define RETURN_ERR( expr ) \
do {\
fex_err_t err = (expr);\
if ( err != NULL )\
return err;\
} while ( 0 )
fex_err_t my_func()
{
RETURN_ERR( fex_foo() );
RETURN_ERR( fex_bar() );
return NULL;
}
If you have your own error codes, you can convert fex's errors to them:
// error codes that differ from library's
enum {
my_ok = 0,
my_generic_error = 123,
my_out_of_memory = 456,
my_file_not_found = 789
// ...
};
int convert_error( fex_err_t err )
{
switch ( fex_err_code( err ) )
{
case fex_ok: return my_ok;
case fex_err_generic: return my_generic_error;
case fex_err_memory: return my_out_of_memory;
case fex_err_file_missing: return my_file_not_found;
// ...
default: return my_generic_error;
}
}
#define RETURN_ERR( expr ) \
do {\
fex_err_t err = (expr);\
if ( err != NULL )\
return convert_error( err );\
} while ( 0 )
int my_func()
{
RETURN_ERR( fex_foo() );
RETURN_ERR( fex_bar() );
return my_ok;
}
The other approach is to pass all errors to an error handler function
that never returns if passed a non-success error value:
// never returns if err != NULL
void handle_error( fex_err_t err );
void my_func()
{
handle_error( fex_foo() );
handle_error( fex_bar() );
}
handle_error() could print the error and exit the program:
void handle_error( fex_err_t err )
{
if ( err != NULL )
{
const char* str = fex_err_str( err );
printf( "Error: %s\n", str );
exit( EXIT_FAILURE );
}
}
handle_error() could also throw a C++ exception (or equivalently in C,
longmp() back to a setjmp() done inside caller()):
void handle_error( fex_err_t err )
{
switch ( fex_err_code( err ) )
{
case fex_ok: return;
case fex_err_memory: throw std::bad_alloc();
// ...
case fex_err_generic:
default:
throw std::runtime_error( fex_err_str( err ) );
}
}
void caller()
{
try
{
my_func();
}
catch ( const std::exception& e )
{
printf( "Error: %s\n", e.what() );
}
}
Solving problems
----------------
If you're having problems, try the following:
* Enable debugging support in your environment. This enables assertions
and other run-time checks. In particular, be sure NDEBUG isn't defined.
* Turn the compiler's optimizer is off. Sometimes an optimizer generates
bad code.
* If multiple threads are being used, ensure that only one at a time is
accessing a given set of objects from the library. This library is not
in general thread-safe, though independent objects can be used in
separate threads.
* If all else fails, see if the demo works.
Thanks
------
Thanks to Richard Bannister, Kode54, byuu, Cless, and DJRobX for testing
and giving feedback for the library. Thanks to the authors of zlib,
unrar, and 7-zip.
--
Shay Green <gblargg@gmail.com>

182
fex/internals.txt
View File

@ -1,91 +1,91 @@
File_Extractor library internals
--------------------------------
This describes the implementation and design.
Contents
--------
* Framework
* Archive abstraction
* 7-ZIP
* ZIP
* RAR
* GZIP
* Binary
Framework
---------
This library is essentially:
* Several archive readers
* Wrappers to provide common interface
* File type detection
The File_Extractor base class implements the common aspects of the
interface and filters out invalid calls. It also provides default
implementations for some operations. Each derived *_Extractor class then
wraps the particular library.
Then fex.h provides a stable, C-compatible wrapper over File_Extractor,
and does file type identification.
Archive abstraction
-------------------
An extractor is abstracted to these fundamental operations:
* Open (either from path or custom reader)
* Iterate over each file
* Extract file's data (either gradually, or all at once into memory)
* Seek to particular file in archive
* Close
The extractor can choose whether to open a file path immediately, or
defer until the first stat() call. When extracting data, it can
implement one or both of normal read and "give me a pointer to the data
already in memory". If it only implements one, File_Extractor will
implement the other in terms of it.
7-ZIP
-----
A fairly simple wrapper over a slightly-modified LZMA library.
Unfortunately you probably won't be able to drop a later version of the
LZMA library sources in and recompile, as the interface and file
arrangement tends to change with every release. The main change I've
made is to declare functions extern "C" in headers, so C++ code can call
them.
ZIP
---
A complete implementation I wrote. Has nifty optimization that makes all
disk reads begin and end on a multiple of 4K. Also minimizes number of
accesses when initially reading catalog, and extracting file data.
Correctly handles empty zip archives, unlike the popular unzip library
which reports it as a bad archive.
RAR
---
Wrapper over heavily-modified UnRAR extraction library based on the
official UnRAR sources. The library is available separately with
documentation and demos, in case you want to use it without the
File_Extractor front-end (see unrar/changes.txt for more).
GZIP
----
Uses zlib's built-in parsing. Also works with non-gzipped files, based
on absence of two-byte Gzip header. Defers opening of file until
fex_stat(), speeding mere scanning of filenames. Gzip_Reader and
Zlib_Reader further divide the implementation into more manageable and
reusable components.
Binary
------
Just a minimal wrapper over C-style FILE.
--
Shay Green <gblargg@gmail.com>
File_Extractor library internals
--------------------------------
This describes the implementation and design.
Contents
--------
* Framework
* Archive abstraction
* 7-ZIP
* ZIP
* RAR
* GZIP
* Binary
Framework
---------
This library is essentially:
* Several archive readers
* Wrappers to provide common interface
* File type detection
The File_Extractor base class implements the common aspects of the
interface and filters out invalid calls. It also provides default
implementations for some operations. Each derived *_Extractor class then
wraps the particular library.
Then fex.h provides a stable, C-compatible wrapper over File_Extractor,
and does file type identification.
Archive abstraction
-------------------
An extractor is abstracted to these fundamental operations:
* Open (either from path or custom reader)
* Iterate over each file
* Extract file's data (either gradually, or all at once into memory)
* Seek to particular file in archive
* Close
The extractor can choose whether to open a file path immediately, or
defer until the first stat() call. When extracting data, it can
implement one or both of normal read and "give me a pointer to the data
already in memory". If it only implements one, File_Extractor will
implement the other in terms of it.
7-ZIP
-----
A fairly simple wrapper over a slightly-modified LZMA library.
Unfortunately you probably won't be able to drop a later version of the
LZMA library sources in and recompile, as the interface and file
arrangement tends to change with every release. The main change I've
made is to declare functions extern "C" in headers, so C++ code can call
them.
ZIP
---
A complete implementation I wrote. Has nifty optimization that makes all
disk reads begin and end on a multiple of 4K. Also minimizes number of
accesses when initially reading catalog, and extracting file data.
Correctly handles empty zip archives, unlike the popular unzip library
which reports it as a bad archive.
RAR
---
Wrapper over heavily-modified UnRAR extraction library based on the
official UnRAR sources. The library is available separately with
documentation and demos, in case you want to use it without the
File_Extractor front-end (see unrar/changes.txt for more).
GZIP
----
Uses zlib's built-in parsing. Also works with non-gzipped files, based
on absence of two-byte Gzip header. Defers opening of file until
fex_stat(), speeding mere scanning of filenames. Gzip_Reader and
Zlib_Reader further divide the implementation into more manageable and
reusable components.
Binary
------
Just a minimal wrapper over C-style FILE.
--
Shay Green <gblargg@gmail.com>

1008
fex/license.txt
View File

File diff suppressed because it is too large Load Diff

118
fex/readme.txt
View File

@ -1,59 +1,59 @@
File_Extractor 1.0.0
--------------------
File_Extractor is a modular archive scanning and extraction library that
supports several popular compressed file formats. It gives a common
interface to the supported formats, allowing one version of user code.
Features:
* Simple C interface.
* Supports ZIP, GZIP, 7-Zip (7Z), and RAR[1] archive formats.
* Non-archive files act like archive of that one file, simplifying code.
* Modular design allows removal of support for unneeded archive formats.
* Optionally supports wide-character paths on Windows.
* Archive file type identification can be customized
[1] RAR support must be enabled before use, due to its special
licensing.
Author : Shay Green <gblargg@gmail.com>
Website : http://code.google.com/p/file-extractor/
License : GNU LGPL 2.1 or later for all except unrar
Language: C interface, C++ implementation
Getting Started
---------------
Build the demo by typing "make" at the command-line. If that doesn't
work, manually build a program from demo.c and all *.c and *.cpp files
in fex/, 7z_C/, and zlib/. Run demo with test.zip in the same directory.
To enable RAR archive support, edit fex/blargg_config.h.
See fex.h for reference and fex.txt for documentation.
Files
-----
fex.txt Manual
license.txt GNU LGPL 2.1 license
makefile Builds libfex.a and demo
demo.c Basic usage
demo_read.c Uses fex_read() to extract data
demo_rewind.c Uses fex_rewind() to re-scan archive
demo_seek.c Uses fex_seek_arc() to go back to files
demo_directory.c Recursively scans directory for archives
demo.zip Test archive used by demos
fex/
blargg_config.h Configuration (modify as needed)
fex.h C interface (also usable from C++)
(all other files) Library sources
zlib/ Zip/Gzip (can use your system's instead)
7z_C/ 7-Zip
unrar/ RAR
--
Shay Green <gblargg@gmail.com>
File_Extractor 1.0.0
--------------------
File_Extractor is a modular archive scanning and extraction library that
supports several popular compressed file formats. It gives a common
interface to the supported formats, allowing one version of user code.
Features:
* Simple C interface.
* Supports ZIP, GZIP, 7-Zip (7Z), and RAR[1] archive formats.
* Non-archive files act like archive of that one file, simplifying code.
* Modular design allows removal of support for unneeded archive formats.
* Optionally supports wide-character paths on Windows.
* Archive file type identification can be customized
[1] RAR support must be enabled before use, due to its special
licensing.
Author : Shay Green <gblargg@gmail.com>
Website : http://code.google.com/p/file-extractor/
License : GNU LGPL 2.1 or later for all except unrar
Language: C interface, C++ implementation
Getting Started
---------------
Build the demo by typing "make" at the command-line. If that doesn't
work, manually build a program from demo.c and all *.c and *.cpp files
in fex/, 7z_C/, and zlib/. Run demo with test.zip in the same directory.
To enable RAR archive support, edit fex/blargg_config.h.
See fex.h for reference and fex.txt for documentation.
Files
-----
fex.txt Manual
license.txt GNU LGPL 2.1 license
makefile Builds libfex.a and demo
demo.c Basic usage
demo_read.c Uses fex_read() to extract data
demo_rewind.c Uses fex_rewind() to re-scan archive
demo_seek.c Uses fex_seek_arc() to go back to files
demo_directory.c Recursively scans directory for archives
demo.zip Test archive used by demos
fex/
blargg_config.h Configuration (modify as needed)
fex.h C interface (also usable from C++)
(all other files) Library sources
zlib/ Zip/Gzip (can use your system's instead)
7z_C/ 7-Zip
unrar/ RAR
--
Shay Green <gblargg@gmail.com>