- surrendered to the incompletenes of breathe. now including only documentation of important stuff by hand.

- added example code using npa-tool.c


git-svn-id: https://vsmartcard.svn.sourceforge.net/svnroot/vsmartcard@569 96b47cad-a561-4643-ad3b-153ac7d7599c

doc/npaapi.rst

@@ -30,12 +30,64 @@ reference since it is more detailed.
 Secure Messaging (SM)
 =====================
 
-.. doxygenfile:: sm.h
+The complete documentation can be found `here
+<_static/doxygen-npa/group__sm.html>`_.
+
+.. doxygenstruct:: sm_ctx
+.. doxygenfunction:: sm_transmit_apdu
+.. doxygenfunction:: sm_ctx_clear_free
 
 ==============================================================
 Interface to German identity card (neuer Personalausweis, nPA)
 ==============================================================
 
-.. doxygenfile:: npa.h
+The complete documentation can be found `here
+<_static/doxygen-npa/group__npa.html>`_.
+
+.. doxygenstruct:: establish_pace_channel_input
+.. doxygenstruct:: establish_pace_channel_output
+.. doxygenfunction:: EstablishPACEChannel
+.. doxygenfunction:: npa_reset_retry_counter
+.. doxygendefine:: npa_change_pin
+.. doxygendefine:: npa_unblock_pin
+
+=======
+Example
+=======
+
+The following example are fragments of the npa-tool, which uses libnpa to acces
+the nPA with and without SM enabled. First set up the environment:
+
+    .. literalinclude:: ../npa/src/npa-tool.c
+        :lines: 49-74,198-212
+
+Connect to a reader and the nPA:
+
+    .. literalinclude:: ../npa/src/npa-tool.c
+        :lines: 331-341
+
+Now we try to change the PIN. Therefor we need to establish a SM channel with
+PACE. You could set your PIN with `pin = "123456"` or just leave it out to be
+asked for it. The same applies to the new PIN `newpin`.
+
+    .. literalinclude:: ../npa/src/npa-tool.c
+        :lines: 484-501
+
+Imagine you want to transmit additional APDUs in the established SM channel.
+Declare the APDU to something like::
+
+    const unsigned char buf[] = {0x00, 0xA4, 0x00, 0x0C, 0x02, 0x3F, 0x00};
+    size_t apdulen = sizeof buf;`
+    sc_apdu_t apdu;
+
+Now parse and transmit the APDU with SM:
+
+    .. literalinclude:: ../npa/src/npa-tool.c
+        :lines: 171-173,175-183,185
+
+Free up memory and wipe it if necessary (e.g. for keys stored in :npa:`sm_ctx`)
+
+    .. literalinclude:: ../npa/src/npa-tool.c
+        :lines: 563-
 
 .. @author Frank Morgner <morgner@informatik.hu-berlin.de>