COLLECTION Create reference to the top level collection

This patch adds ability to create a reference to the top
level collection.
Previously one could get reference only to collection
inside other collection. With this change it becomes
possible to have two pointers to the same top level
collection from multiple places.

COLLECTION Adding comment.

COLLECTION: Some tracing

common/collection/collection.c

@@ -1171,7 +1171,9 @@ static void col_delete_collection(struct collection_item *ci)
         return;
     }
 
-    TRACE_INFO_STRING("Real work to do","");
+    TRACE_INFO_STRING("Real work to do", "");
+    TRACE_INFO_STRING("Property", ci->property);
+    TRACE_INFO_NUMBER("Next item", ci->next);
 
     col_delete_collection(ci->next);
 
@@ -2247,8 +2249,11 @@ void col_destroy_collection(struct collection_item *ci)
         return;
     }
 
+    TRACE_INFO_STRING("Name:", ci->property);
+
     /* Collection can be referenced by other collection */
     header = (struct collection_header *)(ci->data);
+    TRACE_INFO_NUMBER("Reference count:", header->reference_count);
     if (header->reference_count > 1) {
         TRACE_INFO_STRING("Dereferencing a referenced collection.", "");
         header->reference_count--;
@@ -2376,29 +2381,35 @@ int col_get_collection_reference(struct collection_item *ci,
 
     if ((ci == NULL) ||
         (ci->type != COL_TYPE_COLLECTION) ||
-        (acceptor == NULL) ||
-        (collection_to_find == NULL)) {
+        (acceptor == NULL)) {
         TRACE_ERROR_NUMBER("Invalid parameter - returning error",EINVAL);
         return EINVAL;
     }
 
-    /* Find a sub collection */
-    TRACE_INFO_STRING("We are given subcollection name - search it:",
-                      collection_to_find);
-    error = col_find_item_and_do(ci, collection_to_find,
-                                 COL_TYPE_COLLECTIONREF,
-                                 COL_TRAVERSE_DEFAULT,
-                                 col_get_subcollection,
-                                 (void *)(&subcollection),
-                                 COLLECTION_ACTION_FIND);
-    if (error) {
-        TRACE_ERROR_NUMBER("Search failed returning error", error);
-        return error;
-    }
+    if (collection_to_find) {
+        /* Find a sub collection */
+        TRACE_INFO_STRING("We are given subcollection name - search it:",
+                          collection_to_find);
+        error = col_find_item_and_do(ci, collection_to_find,
+                                     COL_TYPE_COLLECTIONREF,
+                                     COL_TRAVERSE_DEFAULT,
+                                     col_get_subcollection,
+                                     (void *)(&subcollection),
+                                     COLLECTION_ACTION_FIND);
+        if (error) {
+            TRACE_ERROR_NUMBER("Search failed returning error", error);
+            return error;
+        }
 
-    if (subcollection == NULL) {
-        TRACE_ERROR_STRING("Search for subcollection returned NULL pointer", "");
-        return ENOENT;
+        if (subcollection == NULL) {
+            TRACE_ERROR_STRING("Search for subcollection returned NULL pointer", "");
+            return ENOENT;
+        }
+    }
+    else {
+        /* Create reference to the same collection */
+        TRACE_INFO_STRING("Creating reference to the top level collection.", "");
+        subcollection = ci;
     }
 
     header = (struct collection_header *)subcollection->data;

common/collection/collection.h

@@ -686,8 +686,10 @@ int col_is_item_in_collection(struct collection_item *ci,   /* Collection to fin
                               int *found);                  /* Boolean that turns to nonzero if the match is found */
 
 
-/* Get collection - get a pointer to a collection included into another collection */
-/* Delete extracted collection after use to decrease reference count. */
+/* Get collection - get a pointer to a collection included into another collection.
+ * If the collection_to_find is NULL function reterns a reference to the top level collection.
+ * Delete extracted collection after use to decrease reference count.
+ */
 int col_get_collection_reference(struct collection_item *ci,          /* High level collection */
                                  struct collection_item **acceptor,   /* The pointer that will accept extracted handle */
                                  const char *collection_to_find);     /* Name to of the collection */

common/collection/collection_ut.c

@@ -33,6 +33,7 @@ int ref_collection_test(void)
 {
     struct collection_item *peer = NULL;
     struct collection_item *socket = NULL;
+    struct collection_item *socket2 = NULL;
     char binary_dump[] = { 0, 1, 2, 3, 4, 5, 6, 7, 8 };
 
     int error = EOK;
@@ -98,7 +99,19 @@ int ref_collection_test(void)
     col_destroy_collection(peer);
 
     col_debug_collection(socket, COL_TRAVERSE_DEFAULT);
+
+    error = col_get_collection_reference(socket, &socket2, NULL);
+    if (error) {
+        col_destroy_collection(socket);
+        printf("Failed to extract collection. Error %d\n", error);
+        return error;
+    }
+
+    col_debug_collection(socket2, COL_TRAVERSE_DEFAULT);
     col_destroy_collection(socket);
+    col_debug_collection(socket2, COL_TRAVERSE_DEFAULT);
+    col_destroy_collection(socket2);
+
     TRACE_FLOW_NUMBER("ref_collection_test. Returning", error);
 
     printf("\n\nEND OF REF TEST!!!.\n\n\n");