libdropbox Files

-------------------------------------------------------------------------------
                   LIBDROPBOX
-------------------------------------------------------------------------------

1.  INTRO

1.1 ABOUT
	Libdropbox is a cross-platform library for the Dropbox REST API. 
	Later on it's also been extended with functions for 
	Windows Azure Service Bus. (Both are REST and rather similar.)
	It features a small self-contained HTTPS module (HTTP 1.1) and a modified 
	version of the small JSMN JSON parser. 
	It was originally based on the 'dropbox_uploader' script, by Andrea Fabrizi. 
	The project is meant for embedded usage. Eg. embedded or small sized Linux. 
	MCUs might not be out of reach either, but the nature of HTTP, TCP and SSL 
	requires a lot of mallocs. You'd need one of the bigger MCUs 
	(perhaps 40k+ ram) plus a framework that's capable of stable mallocs. 
	The original script is based on BASH and cURL. BASH is often replaced by 
	DASH or HUSH these days. And cURL is (or were) based on 
	the OpenSSL library, which is a killer in the embedded world. (cURL takes 
	up 1.2Mb ram on my system.) So, I needed something ANSI C based, with the 
	same features as 'dropbox_uploader' and without the OpenSSL dependency. 

1.2 CREDITS
	The projected is created by me, Morten Kvistgaard, anno 2014.
	Based on 'dropbox_uploader' by Andrea Fabrizi: https://github.com/andreafabrizi/Dropbox-Uploader
	References the PolarSSL library: https://polarssl.org/
	HTTPS Dropbox Core API: https://www.dropbox.com/developers/core/docs
	Windows Azure REST API: http://msdn.microsoft.com/en-us/library/windowsazure/hh780717.aspx

2.  USAGE
	Library usage is most easily demonstrated through the test program 
	'dropbox'. The 'dropbox' app is the equivalent of the original 
	'dropbox_uploader' script. (And it's a fairly useful program by itself.)
	In order to use the Dropbox HTTP API, you first need to register a 
	Dropbox App: https://www.dropbox.com/developers/apps
	The first time you run the script it will ask for a "appkey" and a 
	"appsecret". These are the ones from your Dropbox App. It'll also ask for 
	"access level". This is also determined by your Dropbox App. But most 
	likely it's "App folder/sandbox". Means you should type "a" when the script 
	asks. After that the script will ask you to visit a web page. Something 
	like: https://www2.dropbox.com/1/oauth/authorize?oauth_token=...
	Enter this in your browser, log into your dropbox and approve the request.
	Continue the script. The script is now connected to your dropbox and you'll
	be able to use the features. Eg. like upload/download file.
	The windows_azure is similar to the dropbox.

2.1 LIBRARY API
	The library is rather small and it's meant to be self-documenting. See the 
	"dropbox.h" or the "windows_azure.h" file.

3.  TECHNICAL

3.1 COMPILING
	Makefiles has always been a bitch in my book. Especially when it comes to
	cross-platform makefiles and projects that relies on external dependencies.
	Maybe I should create a Visual Studio project for the win32 compile. I 
	prefer to work in Eclipse and MinGW through. The good thing is, the project
	doesn't contain that many files. If in trouble, ignore the makefiles and 
	let Eclipse build the library by it self. 

3.1.1 CREATE NEW APP (NEW COMPILE SCRIPT)
	If you create you own compile script. Eg. if you want to make Eclipse do 
	the compilation. You need to link with libdropbox and libpolarssl. And in
	Windows you also need Ws2_32.lib. The order of inclusion is 
	important. The correct order is: -ldropbox -lpolarssl -lWs2_32.
	This is only relevant when using static linking, I think. 

3.1.2 LINUX COMPILE
	First download the PolarSSL v. 1.3.4 (higher might also work). Compile it
	with "make" or "make SHARED=1" and install it with "make install". 
	Same with the library: "make" or "make SHARED=1" and (maybe) 
	"make install". You should be able to run something like "dropbox --info"
	now.
	
3.1.3 WIN32 COMPILE
	Currently, you need MinGW + MSYS to compile the library on Windows. (So 
	make sure you've installed those.)
	Download the PolarSSL v. 1.3.4 (higher might also work) and place it in the
	same folder as libdropbox. (Place the 'polarssl-1.3.4' folder next to the 
	'library' folder in libdropbox. Now compile all of it with "make WINDOWS=1"
	or "make WINDOWS=1 SHARED=1". The test application 'dropbox.exe' has now 
	been built and is placed in 'programs/dropbox'. Try to run something like
	'programs/dropbox/dropbox --info'. 

3.1.4 SHARED/FPIC/DLL
	The project can be built as a shared library also. Just call:
	make SHARED=1

3.1.5 DEBUG
	The project can be build in debug mode:
	make DEBUG=1

4.  TESTS
	All the functions has been tested up against the official Dropbox Server.
	No other tests, like eg. generic https usage has been performed.

5.  SUPPORT
	There's no support for the project at this time. That's reserved for our 
	customers. If you write to me, I'm unlikely to answer. 

6.  REPORT ERRORS
	Try writing to me at mk@pch-engineering.dk.

7.  CONTRIBUTE
	Really? You think it's missing something? It's not really meant as a huge 
	glorified project you know, but if you really must, try contacting me
	at mk@pch-engineering.dk.
	
8.  MISC
	Project web page is located at: 
	https://sourceforge.net/projects/libdropbox/