Improve naming consistency.

Ensure all MIFARE related names and structures start with "mifare_" or
"MIFARE_".

HACKING.md

@@ -0,0 +1,98 @@
+Hello hackers!
+
+# General remarks about contributing
+
+Contributions to the libfreefare are welcome!  Here are some directions to get
+you started:
+
+## Install Cutter
+
+[Cutter](http://cutter.sourceforge.net/) is a cool unit test framework for C
+code.  You will need it to run the regression tests suite (`make check`) and
+ensure that your code does not break other features.
+
+To cover all tests you'll need several blank cards:
+
+* MIFARE Classic 4k with default keys (`FFFFFFFFFF`)
+* MIFARE DESFire EV1 4k with default PICC key (`0000000000000000`)
+* MIFARE Ultralight
+* MIFARE Ultralight C with default key (`BREAKMEIFYOUCAN!`)
+
+After "make check", you can run sub-sets of tests directly with cutter:
+
+~~~
+$ cutter -n /ultralight/ test
+$ cutter -n /classic/ test
+$ cutter -n /desfire/ test
+~~~
+
+## Follow style conventions
+
+The source code of the library trend to follow some conventions so that it is
+consistent in style and thus easier to read.  Basically, it follows [FreeBSD's
+style(9)](http://www.freebsd.org/cgi/man.cgi?query=style); adding 4-space
+indentation and 8-space tabs (which you should configure in your editor, e.g.
+`:set sw=4 ts=8` in vim).  You are also advised to `:set cinoptions=t0(0:0` so
+that you don't have to care about indentation anymore. For more details, please
+read the [style(9) man page from FreeBSD's
+website](http://www.freebsd.org/cgi/man.cgi?query=style).
+
+## Write tests
+
+I already told you cutter is lovely, so you really should use it!  If you want
+to contribute code, write test: only code with appropriate tests will be
+considered.  And remember that
+[TDD](http://en.wikipedia.org/wiki/Test-driven_development) (Test Driven
+Development) is cool and writing all tests at the end deeply depressing, so
+test early, test often!
+
+# Adding support for a new type of card
+
+Adding a new supported card to the libfreefare requires a few modification in
+multiple places.  Here is a list of the things to do in order to have the
+infrastructure ready for hacking the new card support:
+
+  - Edit `libfreefare/freefare.h`:
+    - Add your tag to the `freefare_tag_type` enum;
+    - Add a `<tag>_connect()` and a `<tag>_disconnect()` function prototype;
+  - Edit `libfreefare/freefare.3`:
+    - Add your tag to the `freefare_tag_type' enum documentation;
+  - Edit `libfreefare/freefare_internal.h`:
+    - Add a new `<tag>_tag struct`.  It's very first member SHALL be `struct
+      freefare_tag __tag`;
+    - Add a `<tag>_tag_new()` and a `<tag>_tag_free()` function prototype;
+    - Add a `ASSERT_<TAG>()` macro to check the tag's type;
+    - Add a `<TAG>()` macro to cast a generic tag to your type.
+  - Edit `libfreefare/freefare.c`:
+    - Add your tag type to the supported_tags array;
+    - Edit the `freefare_get_tags()` function so that it calls `<tag>_tag_new()`
+      when it finds your tag;
+    - Edit the `freefare_free_tags()` function so that it calls
+      `<tag>_tag_free()` to free your tags;
+  - Create `libfreefare/<tag>.c` and implement all that's missing:
+    - `<tag>_tag_new()` MUST allocate all data-structure the tag may need to
+      use during it's lifetime.  We do not want to have any function to fail
+      later because the running system is out of resources.  Buffers for
+      cryptographic operations on random amount of data MAY however be
+      (re)allocated on demand, in such case refrain from shrinking
+      unnecessarily the buffer size.
+    - `<tag>_connect()` SHOULD initialise data allocated by `<tag>_tag_new()`.
+      Keep in mind that a single tag may be disconnected from and connected
+      to again, without being freed in the meantime.  Since all memory
+      allocations are done in `<tag>_tag_new()`, your code SHOULD only care
+      about initialising these data structures;
+    - `<tag>_disconnect()` MAY do more that just send a disconnect command to
+      the tag.  At time of writing I have no idea what it could be but who
+      knows...
+    - `<tag>_tag_free()` SHALL free all resources allocated for the tag
+      (surprising, isn't it?)
+
+# Various guidelines
+
+  - If a given card has different cryptographic modes, you SHOULD use
+    switch/cases to handle specific branches of code, even when applicable to
+    only one cypher.  The idea is that if you don't provide support for all
+    cryptographic schemes, or if an evolution of the card provides more
+    cryptographic possibilities, when adding support for a new cypher, the
+    compiler can warn the developer about unhandled values in switch
+    statements.  Please refer to the MIFARE DESFire code for an example.

examples/mifare-classic-format.c

@@ -215,8 +215,8 @@ main(int argc, char *argv[])
 
 	for (int i = 0; (!error) && tags[i]; i++) {
 	    switch (freefare_get_tag_type (tags[i])) {
-	    case CLASSIC_1K:
-	    case CLASSIC_4K:
+	    case MIFARE_CLASSIC_1K:
+	    case MIFARE_CLASSIC_4K:
 		break;
 	    default:
 		continue;
@@ -240,24 +240,24 @@ main(int argc, char *argv[])
 		at_block = 0;
 
 		if (format_options.fast) {
-		    printf (START_FORMAT_N, (tt == CLASSIC_1K) ? 1 : 2);
+		    printf (START_FORMAT_N, (tt == MIFARE_CLASSIC_1K) ? 1 : 2);
 		    if (!try_format_sector (tags[i], 0x00))
 			break;
 
-		    if (tt == CLASSIC_4K)
+		    if (tt == MIFARE_CLASSIC_4K)
 			if (!try_format_sector (tags[i], 0x10))
 			    break;
 
 		    printf (DONE_FORMAT);
 		    continue;
 		}
 		switch (tt) {
-		case CLASSIC_1K:
+		case MIFARE_CLASSIC_1K:
 		    mod_block = 4;
 		    if (!format_mifare_classic_1k (tags[i]))
 			error = 1;
 		    break;
-		case CLASSIC_4K:
+		case MIFARE_CLASSIC_4K:
 		    mod_block = 10;
 		    if (!format_mifare_classic_4k (tags[i]))
 			error = 1;

examples/mifare-classic-read-ndef.c

@@ -139,8 +139,8 @@ main(int argc, char *argv[])
 
 	for (int i = 0; (!error) && tags[i]; i++) {
 	    switch (freefare_get_tag_type (tags[i])) {
-	    case CLASSIC_1K:
-	    case CLASSIC_4K:
+	    case MIFARE_CLASSIC_1K:
+	    case MIFARE_CLASSIC_4K:
 		break;
 	    default:
 		continue;

examples/mifare-classic-write-ndef.c

@@ -229,8 +229,8 @@ main(int argc, char *argv[])
 
 	for (int i = 0; (!error) && tags[i]; i++) {
 	    switch (freefare_get_tag_type (tags[i])) {
-	    case CLASSIC_1K:
-	    case CLASSIC_4K:
+	    case MIFARE_CLASSIC_1K:
+	    case MIFARE_CLASSIC_4K:
 		break;
 	    default:
 		continue;
@@ -257,13 +257,13 @@ main(int argc, char *argv[])
 
 	    if (write_ndef) {
 		switch (freefare_get_tag_type (tags[i])) {
-		case CLASSIC_4K:
+		case MIFARE_CLASSIC_4K:
 		    if (!search_sector_key (tags[i], 0x10, &(card_write_keys[0x10].key), &(card_write_keys[0x10].type))) {
 			error = 1;
 			goto error;
 		    }
 		    /* fallthrough */
-		case CLASSIC_1K:
+		case MIFARE_CLASSIC_1K:
 		    if (!search_sector_key (tags[i], 0x00, &(card_write_keys[0x00].key), &(card_write_keys[0x00].type))) {
 			error = 1;
 			goto error;
@@ -277,7 +277,7 @@ main(int argc, char *argv[])
 		if (!error) {
 		    /* Ensure the auth key is always a B one. If not, change it! */
 		    switch (freefare_get_tag_type (tags[i])) {
-		    case CLASSIC_4K:
+		    case MIFARE_CLASSIC_4K:
 			if (card_write_keys[0x10].type != MFC_KEY_B) {
 			    if( 0 != fix_mad_trailer_block (device, tags[i], 0x10, card_write_keys[0x10].key, card_write_keys[0x10].type)) {
 				error = 1;
@@ -287,7 +287,7 @@ main(int argc, char *argv[])
 			    card_write_keys[0x10].type = MFC_KEY_B;
 			}
 			/* fallthrough */
-		    case CLASSIC_1K:
+		    case MIFARE_CLASSIC_1K:
 			if (card_write_keys[0x00].type != MFC_KEY_B) {
 			    if( 0 != fix_mad_trailer_block (device, tags[i], 0x00, card_write_keys[0x00].key, card_write_keys[0x00].type)) {
 				error = 1;
@@ -336,18 +336,18 @@ main(int argc, char *argv[])
 		} else {
 
 		    // Create a MAD and mark unaccessible sectors in the card
-		    if (!(mad = mad_new ((freefare_get_tag_type (tags[i]) == CLASSIC_4K) ? 2 : 1))) {
+		    if (!(mad = mad_new ((freefare_get_tag_type (tags[i]) == MIFARE_CLASSIC_4K) ? 2 : 1))) {
 			perror ("mad_new");
 			error = 1;
 			goto error;
 		    }
 
 		    MifareClassicSectorNumber max_s = 0;
 		    switch (freefare_get_tag_type (tags[i])) {
-		    case CLASSIC_1K:
+		    case MIFARE_CLASSIC_1K:
 			max_s = 15;
 			break;
-		    case CLASSIC_4K:
+		    case MIFARE_CLASSIC_4K:
 			max_s = 39;
 			break;
 		    default:

examples/mifare-desfire-access.c

@@ -63,7 +63,7 @@ main(int argc, char *argv[])
 	}
 
 	for (int i = 0; (!error) && tags[i]; i++) {
-	    if (DESFIRE != freefare_get_tag_type (tags[i]))
+	    if (MIFARE_DESFIRE != freefare_get_tag_type (tags[i]))
 		continue;
 
 	    int res;

examples/mifare-desfire-create-ndef.c

@@ -119,7 +119,7 @@ main(int argc, char *argv[])
 	}
 
 	for (int i = 0; (!error) && tags[i]; i++) {
-	    if (DESFIRE != freefare_get_tag_type (tags[i]))
+	    if (MIFARE_DESFIRE != freefare_get_tag_type (tags[i]))
 		continue;
 
 	    char *tag_uid = freefare_get_tag_uid (tags[i]);

examples/mifare-desfire-ev1-configure-ats.c

@@ -111,7 +111,7 @@ main(int argc, char *argv[])
 	}
 
 	for (int i = 0; (!error) && tags[i]; i++) {
-	    if (DESFIRE != freefare_get_tag_type (tags[i]))
+	    if (MIFARE_DESFIRE != freefare_get_tag_type (tags[i]))
 		continue;
 
 	    char *tag_uid = freefare_get_tag_uid (tags[i]);

examples/mifare-desfire-ev1-configure-default-key.c

@@ -97,7 +97,7 @@ main(int argc, char *argv[])
 	}
 
 	for (int i = 0; (!error) && tags[i]; i++) {
-	    if (DESFIRE != freefare_get_tag_type (tags[i]))
+	    if (MIFARE_DESFIRE != freefare_get_tag_type (tags[i]))
 		continue;
 
 	    char *tag_uid = freefare_get_tag_uid (tags[i]);

examples/mifare-desfire-ev1-configure-random-uid.c

@@ -107,7 +107,7 @@ main(int argc, char *argv[])
 	}
 
 	for (int i = 0; (!error) && tags[i]; i++) {
-	    if (DESFIRE != freefare_get_tag_type (tags[i]))
+	    if (MIFARE_DESFIRE != freefare_get_tag_type (tags[i]))
 		continue;
 
 	    char *tag_uid = freefare_get_tag_uid (tags[i]);

examples/mifare-desfire-format.c

@@ -107,7 +107,7 @@ main(int argc, char *argv[])
 	}
 
 	for (int i = 0; (!error) && tags[i]; i++) {
-	    if (DESFIRE != freefare_get_tag_type (tags[i]))
+	    if (MIFARE_DESFIRE != freefare_get_tag_type (tags[i]))
 		continue;
 
 	    char *tag_uid = freefare_get_tag_uid (tags[i]);

examples/mifare-desfire-info.c

@@ -61,7 +61,7 @@ main(int argc, char *argv[])
 	}
 
 	for (int i = 0; (!error) && tags[i]; i++) {
-	    if (DESFIRE != freefare_get_tag_type (tags[i]))
+	    if (MIFARE_DESFIRE != freefare_get_tag_type (tags[i]))
 		continue;
 
 	    int res;

examples/mifare-desfire-read-ndef.c

@@ -147,7 +147,7 @@ main(int argc, char *argv[])
 	}
 
 	for (int i = 0; (!error) && tags[i]; i++) {
-	    if (DESFIRE != freefare_get_tag_type (tags[i]))
+	    if (MIFARE_DESFIRE != freefare_get_tag_type (tags[i]))
 		continue;
 
 	    char *tag_uid = freefare_get_tag_uid (tags[i]);

examples/mifare-desfire-write-ndef.c

@@ -176,7 +176,7 @@ main(int argc, char *argv[])
 	}
 
 	for (int i = 0; (!error) && tags[i]; i++) {
-	    if (DESFIRE != freefare_get_tag_type (tags[i]))
+	    if (MIFARE_DESFIRE != freefare_get_tag_type (tags[i]))
 		continue;
 
 	    char *tag_uid = freefare_get_tag_uid (tags[i]);