README

= ======== =
= libzippp =
= ======== =

libzippp is a simple basic C++ wrapper around the libzip library.
It is meant to be a portable and easy-to-use library for Zip handling.

Compilation works with:
- gcc 4.7.3
- MS Visual Studio 2012

= ============ =
= Compilation  =
= ============ =

-----
LINUX
-----

0) make sure you have the following commands: g++ make tar wget

1) download and compile de libzip library with the following command:
	make libzip

2) then create the static and shared libraries of libzippp:
	make

3) you may want to run the tests:
	make tests

4) now you just have to include the src folder in your include path and
   link against libzippp.a or libzippp.so (do not forget to also link 
   against libzip libraries in lib/libzip-0.11.2/lib/.libs/).
   An example of compilation with g++ (note also the -lz at the end) :
   	g++ -I./lib/libzip-0.11.2/lib -I./src \
		main.cpp libzippp.a \
		lib/libzip-0.11.2/lib/.libs/libzip.a \
		-lz

-------
WINDOWS
-------

0) make sure you have cmake (cmake.exe must be in the PATH) and MS Visual 
   Studio 2012. The dev command prompt path should be (defined in compile.bat):
     <MSVS11>\Common7\Tools\VsDevCmd.bat

1) download libzip and zlib and extract them in a folder called 'lib'.
   you should have the following structure:
     libzippp/compile.bat
     libzippp/lib/zlib-1.2.8
     libzippp/lib/libzip-0.11.2

2) execute the compile.bat (simply double-click on it). the compilation should 
   go without error.

3) you'll have a 'dist' folder containing the 'release' and 'debug' folders 
   where you can now execute the libzippp tests.

4) you can either use libzippp.dll and libzippp.lib to link dynamically the 
   library or simply use libzippp_static.lib to link it statically. Unless you 
   also link zlib and libzippp statically, you'll need the dll packaged with 
   your executable.


= ===== =
= Usage =
= ===== =

The API is meant to be very straight forward. Some french explanations
can be found here: http://www.astorm.ch/blog

How to list and read files in an archive:

	#include "libzippp.h"
	using namespace libzippp;

	ZipArchive zf("archive.zip");
	zf.open(ZipArchive::READ_ONLY);

	vector<ZipEntry> entries = zf.getEntries();
	vector<ZipEntry>::iterator it;
	for(it=entries.begin() ; it!=entries.end(); ++it) {
		ZipEntry entry = *it;
		string name = entry.getName();
		int size = entry.getSize();

		//the length of binaryData will be size
		void* binaryData = entry.readAsBinary();

		//the length of textData will be size
		string textData = entry.readAsText();

		//...
	}

	zf.close();


How to read a specific entry from an archive:

	#include "libzippp.h"
	using namespace libzippp;

	ZipArchive zf("archive.zip");
	zf.open(ZipArchive::READ_ONLY);

        //direct way
	char* data = (char*)zf.readEntry("myFile.txt", true);
	string str1(data, entry.getSize());

        //indirect way
	ZipEntry entry = zf.getEntry("myFile.txt");
	string str2 = entry.readAsText();

	zf.close();


How to add data to an archive:

	#include "libzippp.h"
	using namespace libzippp;

	ZipArchive zf("archive.zip");
	zf.open(ZipArchive::WRITE);
	zf.addEntry("folder/subdir/");

	const char* textData = "Hello,World!";
	zf.addData("helloworld.txt", textData, 12);

	zf.close();


How to remove data from an archive:

	#include "libzippp.h"
	using namespace libzippp;

	ZipArchive zf("archive.zip");
	zf.open(ZipArchive::WRITE);
	zf.deleteEntry("myFile.txt");
	zf.deleteEntry("myDir/subDir/");
	zf.close();


= ====== =
= TODO   =
= ====== =

- Extra field handling


= ====== =
= ISSUES =
= ====== =

-----
LINUX
-----

You might already have libzip compiled elsewhere on your system. Hence, you
don't need to run 'make libzip'. Instead, just put the libzip location when
you compile libzipp:
	make LIBZIP=path/to/libzip

-------
WINDOWS
-------

By default, MS Visual Studio 2012 is installed under the following path:
  C:\Program Files (x86)\Microsoft Visual Studio 11.0\

Be aware that non-virtual-only classes are shared within the DLL of libzippp.
Hence you'll need to use the same compiler for libzippp and the pieces of code
that will use it. To avoid this issue, you'll have to link the library statically.
More information: http://www.codeproject.com/Articles/28969/HowTo-Export-C-classes-from-a-DLL