[aravis] chunk_parser: improve the documentation with a sample code

[Emmanuel Pacaud <emmanuel src gnome org>]

commit d571ecd5b0da459d99a544cd64af75070c3d6dd7
Author: Emmanuel Pacaud <emmanuel gnome org>
Date:   Tue Aug 19 23:57:53 2014 +0200

    chunk_parser: improve the documentation with a sample code

 docs/reference/aravis/aravis-sections.txt |    2 +-
 src/arvchunkparser.c                      |   52 +++++++++++++++++++++++-
 src/arvchunkparser.h                      |    1 +
 tests/.gitignore                          |    1 +
 tests/Makefile.am                         |   13 +++++-
 tests/arvchunkparsertest.c                |   63 +++++++++++++++++++++++++++++
 6 files changed, 129 insertions(+), 3 deletions(-)
---
diff --git a/docs/reference/aravis/aravis-sections.txt b/docs/reference/aravis/aravis-sections.txt
index e5ecb12..3ceb3f3 100644
--- a/docs/reference/aravis/aravis-sections.txt
+++ b/docs/reference/aravis/aravis-sections.txt
@@ -282,7 +282,6 @@ ARV_DEVICE_NAME_REPLACEMENT_CHARACTER
 <FILE>arvchunkparser</FILE>
 <TITLE>ArvChunkParser</TITLE>
 ArvChunkParser
-ArvChunkParserStatus
 arv_chunk_parser_new
 arv_chunk_parser_get_float_value
 arv_chunk_parser_get_integer_value
@@ -296,6 +295,7 @@ ARV_IS_CHUNK_PARSER
 ARV_IS_CHUNK_PARSER_CLASS
 ARV_TYPE_CHUNK_PARSER
 <SUBSECTION Private>
+ArvChunkParserStatus
 ArvChunkParserPrivate
 ARV_CHUNK_PARSER_ERROR
 </SECTION>
diff --git a/src/arvchunkparser.c b/src/arvchunkparser.c
index d8df3cc..e4a7066 100644
--- a/src/arvchunkparser.c
+++ b/src/arvchunkparser.c
@@ -26,6 +26,23 @@
  *
  * #ArvChunkParser provides a class for the instantiation of chunk parsers used
  * for the extraction of chunk data stored in the stream payload.
+ *
+ * Chunks are tagged blocks of data stored in a #ArvBuffer containing
+ * a #ARV_BUFFER_PAYLOAD_TYPE_CHUNK_DATA payload. The tags allow a chunk
+ * parser to dissect the data payload into its elements and to identify the content.
+ *
+ * Chunk data are enabled using either arv_camera_set_chunks() or
+ * arv_camera_set_chunk_mode(). Both functions are simple convenience wrappers
+ * that handle the setting of ChunkModeActive, ChunkSelector and ChunkEnable
+ * GENICAM features.
+ *
+ * <example id="arv-chunk-parser-test"><title>Example use of the ArvChunkParser API</title>
+ * <programlisting>
+ * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" 
href="../../../../tests/arvchunkparsertest.c">
+ *   <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
+ * </xi:include>
+ * </programlisting>
+ * </example>
  */
 
 #include <arvchunkparserprivate.h>
@@ -53,6 +70,17 @@ struct _ArvChunkParserPrivate {
        ArvGc *genicam;
 };
 
+/**
+ * arv_chunk_parser_get_string_value:
+ * @parser: a #ArvChunkParser
+ * @buffer: a #ArvBuffer with a #ARV_BUFFER_PAYLOAD_TYPE_CHUNK_DATA payload
+ * @chunk: chunk data name
+ *
+ * Gets the value of chunk data as a string.
+ *
+ * Returns: the chunk data string value.
+ */
+
 const char *
 arv_chunk_parser_get_string_value (ArvChunkParser *parser, ArvBuffer *buffer, const char *chunk)
 {
@@ -73,6 +101,17 @@ arv_chunk_parser_get_string_value (ArvChunkParser *parser, ArvBuffer *buffer, co
        return string;
 }
 
+/**
+ * arv_chunk_parser_get_integer_value:
+ * @parser: a #ArvChunkParser
+ * @buffer: a #ArvBuffer with a #ARV_BUFFER_PAYLOAD_TYPE_CHUNK_DATA payload
+ * @chunk: chunk data name
+ *
+ * Gets the value of chunk data as an integer.
+ *
+ * Returns: the chunk data integer value.
+ */
+
 gint64
 arv_chunk_parser_get_integer_value (ArvChunkParser *parser, ArvBuffer *buffer, const char *chunk)
 {
@@ -93,6 +132,17 @@ arv_chunk_parser_get_integer_value (ArvChunkParser *parser, ArvBuffer *buffer, c
        return value;
 }
 
+/**
+ * arv_chunk_parser_get_float_value:
+ * @parser: a #ArvChunkParser
+ * @buffer: a #ArvBuffer with a #ARV_BUFFER_PAYLOAD_TYPE_CHUNK_DATA payload
+ * @chunk: chunk data name
+ *
+ * Gets the value of chunk data as a float.
+ *
+ * Returns: the chunk data float value.
+ */
+
 double
 arv_chunk_parser_get_float_value (ArvChunkParser *parser, ArvBuffer *buffer, const char *chunk)
 {
@@ -116,7 +166,7 @@ arv_chunk_parser_get_float_value (ArvChunkParser *parser, ArvBuffer *buffer, con
 /**
  * arv_chunk_parser_new:
  * @xml: XML genicam data
- * @size: data size, -1 if NULL terminated
+ * @size: genicam data size, -1 if NULL terminated
  *
  * Creates a new chunk_parser.
  *
diff --git a/src/arvchunkparser.h b/src/arvchunkparser.h
index 13c29b9..fd2a20d 100644
--- a/src/arvchunkparser.h
+++ b/src/arvchunkparser.h
@@ -37,6 +37,7 @@ G_BEGIN_DECLS
  */
 
 typedef enum {
+       /* < private> */
        ARV_CHUNK_PARSER_STATUS_UNKNOWN = -1,
        ARV_CHUNK_PARSER_STATUS_SUCCESS =  0,
        ARV_CHUNK_PARSER_STATUS_BUFFER_NOT_FOUND,
diff --git a/tests/.gitignore b/tests/.gitignore
index cf27c42..998fdcd 100644
--- a/tests/.gitignore
+++ b/tests/.gitignore
@@ -9,6 +9,7 @@ arv-genicam-test
 arv-evaluator-test
 arv-zip-test
 arv-camera-test
+arv-chunk-parser-test
 arv-heartbeat-test
 arv-example
 time-test
diff --git a/tests/Makefile.am b/tests/Makefile.am
index 498d19a..4ec2d5b 100644
--- a/tests/Makefile.am
+++ b/tests/Makefile.am
@@ -8,7 +8,15 @@ test_progs_ldadd =                                     \
        $(top_builddir)/src/libaravis- ARAVIS_API_VERSION@.la           \
        $(ARAVIS_LIBS)
 
-noinst_PROGRAMS = arv-test arv-genicam-test arv-evaluator-test arv-zip-test arv-camera-test 
arv-heartbeat-test arv-example time-test
+noinst_PROGRAMS =                      \
+       arv-test                        \
+       arv-genicam-test                \
+               arv-evaluator-test              \
+               arv-zip-test                    \
+               arv-camera-test                 \
+       arv-chunk-parser-test           \
+               arv-heartbeat-test              \
+               arv-example time-test
 
 arv_test_SOURCES = arvtest.c
 arv_test_LDADD = $(test_progs_ldadd)
@@ -25,6 +33,9 @@ arv_zip_test_LDADD = $(test_progs_ldadd)
 arv_camera_test_SOURCES = arvcameratest.c
 arv_camera_test_LDADD = $(test_progs_ldadd)
 
+arv_chunk_parser_test_SOURCES = arvchunkparsertest.c
+arv_chunk_parser_test_LDADD = $(test_progs_ldadd)
+
 arv_heartbeat_test_SOURCES = arvheartbeattest.c
 arv_heartbeat_test_LDADD = $(test_progs_ldadd)
 
diff --git a/tests/arvchunkparsertest.c b/tests/arvchunkparsertest.c
new file mode 100644
index 0000000..56cbc62
--- /dev/null
+++ b/tests/arvchunkparsertest.c
@@ -0,0 +1,63 @@
+#include <arv.h>
+#include <stdio.h>
+
+int
+main (int argc, char **argv)
+{
+       ArvCamera *camera;
+       ArvStream *stream;
+       ArvChunkParser *parser;
+
+       /* Mandatory glib type system initialization */
+       arv_g_type_init ();
+
+       /* Instantiation of the first available camera */
+       camera = arv_camera_new (NULL);
+
+       if (camera != NULL) {
+               gint payload;
+
+               /* Instantiation of a chunk parser */
+               parser = arv_camera_create_chunk_parser (camera);
+
+               /* Enable chunk data */
+               arv_camera_set_chunks (camera, "ChunkWidth,ChunkHeight");
+
+               /* retrieve image payload (number of bytes per image) */
+               payload = arv_camera_get_payload (camera);
+
+               /* Create a new stream object */
+               stream = arv_camera_create_stream (camera, NULL, NULL);
+
+               if (stream != NULL) {
+                       ArvBuffer *buffer;
+
+                       /* Push 1 buffer in the stream input buffer queue */
+                       arv_stream_push_buffer (stream, arv_buffer_new (payload, NULL));
+
+                       /* Start the video stream */
+                       arv_camera_start_acquisition (camera);
+
+                       /* Retrieve the acquired buffer */
+                       buffer = arv_stream_pop_buffer (stream);
+
+                       printf ("ChunkWidth = %d\n", (int) arv_chunk_parser_get_integer_value (parser, 
buffer, "ChunkWidth"));
+                       printf ("ChunkHeight = %d\n", (int) arv_chunk_parser_get_integer_value (parser, 
buffer, "ChunkHeight"));
+
+                       g_object_unref (buffer);
+
+                       /* Stop the video stream */
+                       arv_camera_stop_acquisition (camera);
+
+                       g_object_unref (stream);
+               } else
+                       printf ("Can't create stream thread (check if the device is not already used)\n");
+
+               g_object_unref (parser);
+               g_object_unref (camera);
+       } else
+               printf ("No camera found\n");
+
+       return 0;
+}
+