uci: libuci leaking memory on non-existent config file
[project/uci.git] / ucimap.h
index d0e8ce9..8386fff 100644 (file)
--- a/ucimap.h
+++ b/ucimap.h
@@ -1,21 +1,25 @@
 /*
- * ucimap - library for mapping uci sections into data structures
- * Copyright (C) 2008 Felix Fietkau <nbd@openwrt.org>
+ * ucimap.h - Library for the Unified Configuration Interface
+ * Copyright (C) 2008-2009 Felix Fietkau <nbd@openwrt.org>
  *
  * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
+ * it under the terms of the GNU Lesser General Public License version 2.1
  * as published by the Free Software Foundation
  *
  * This program is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
+ * GNU Lesser General Public License for more details.
  */
+
+/*
+ * This file contains ucimap, an API for mapping UCI to C data structures 
+ */
+
 #ifndef __UCIMAP_H
 #define __UCIMAP_H
 
 #include <stdbool.h>
-#include "uci_list.h"
 #include "uci.h"
 
 #ifndef ARRAY_SIZE
 
 struct uci_sectionmap;
 struct uci_optmap;
+
 struct ucimap_list;
-struct uci_alloc;
-struct uci_alloc_custom;
+struct ucimap_fixup;
+struct ucimap_alloc;
+struct ucimap_alloc_custom;
+struct ucimap_section_data;
 
 struct uci_map {
        struct uci_sectionmap **sections;
        unsigned int n_sections;
-       struct list_head sdata;
-       struct list_head fixup;
-       struct list_head pending;
        bool parsed;
-
-       void *priv; /* user data */
+       void *priv;
+
+       /* private */
+       struct ucimap_fixup *fixup;
+       struct ucimap_fixup **fixup_tail;
+       struct ucimap_section_data *sdata;
+       struct ucimap_section_data *pending;
+       struct ucimap_section_data **sdata_tail;
 };
 
 enum ucimap_type {
@@ -148,26 +158,20 @@ union ucimap_data {
 };
 
 struct ucimap_section_data {
-       struct list_head list;
        struct uci_map *map;
        struct uci_sectionmap *sm;
        const char *section_name;
 
-       /* list of allocations done by ucimap */
-       struct uci_alloc *allocmap;
-       struct uci_alloc_custom *alloc_custom;
-       unsigned int allocmap_len;
-       unsigned int alloc_custom_len;
-
        /* map for changed fields */
        unsigned char *cmap;
        bool done;
-};
 
-
-struct uci_listmap {
-       struct list_head list;
-       union ucimap_data data;
+       /* internal */
+       struct ucimap_section_data *next, **ref;
+       struct ucimap_alloc *allocmap;
+       struct ucimap_alloc_custom *alloc_custom;
+       unsigned int allocmap_len;
+       unsigned int alloc_custom_len;
 };
 
 struct uci_sectionmap {
@@ -228,15 +232,93 @@ struct uci_optmap {
 
 struct ucimap_list {
        int n_items;
+       int size;
        union ucimap_data item[];
 };
 
+/**
+ * ucimap_init: initialize the ucimap data structure
+ * @map: ucimap data structure
+ *
+ * you must call this function before doing any other ucimap operation
+ * on the data structure
+ */
 extern int ucimap_init(struct uci_map *map);
+
+/**
+ * ucimap_cleanup: clean up all allocated data from ucimap
+ * @map: ucimap data structure
+ */
 extern void ucimap_cleanup(struct uci_map *map);
+
+/**
+ * ucimap_parse: parse all sections in an uci package using ucimap
+ * @map: ucimap data structure
+ * @pkg: uci package
+ */
+extern void ucimap_parse(struct uci_map *map, struct uci_package *pkg);
+
+/**
+ * ucimap_set_changed: mark a field in a custom data structure as changed
+ * @sd: pointer to the ucimap section data
+ * @field: pointer to the field inside the custom data structure
+ *
+ * @sd must be set to the section data inside the data structure that contains @field
+ */
 extern void ucimap_set_changed(struct ucimap_section_data *sd, void *field);
+
+/**
+ * ucimap_store_section: copy all changed data from the converted data structure to uci
+ * @map: ucimap data structure
+ * @p: uci package to store the changes in
+ * @sd: pointer to the ucimap section data
+ *
+ * changes are not saved or committed automatically
+ */
 extern int ucimap_store_section(struct uci_map *map, struct uci_package *p, struct ucimap_section_data *sd);
-extern void ucimap_parse(struct uci_map *map, struct uci_package *pkg);
+
+/**
+ * ucimap_parse_section: parse a single section
+ * @map: ucimap data structure
+ * @sm: uci section map
+ * @sd: pointer to the ucimap section data
+ * @s: pointer to the uci section
+ *
+ * this function overwrites the ucimap section data, do not use on a section
+ * that has been parsed already
+ */
 extern int ucimap_parse_section(struct uci_map *map, struct uci_sectionmap *sm, struct ucimap_section_data *sd, struct uci_section *s);
+
+/**
+ * ucimap_free_section: free a data structure for a converted section
+ * @map: ucimap data structure
+ * @sd: pointer to the ucimap section data
+ *
+ * this function will clean up all data that was allocated by ucimap for this section.
+ * all references to the data structure become invalid
+ */
 extern void ucimap_free_section(struct uci_map *map, struct ucimap_section_data *sd);
 
+/**
+ * ucimap_resize_list: allocate or resize a uci list
+ * @sd: pointer to the ucimap section data
+ * @list: pointer to the list field
+ * @items: new size
+ *
+ * @sd must point to the data structure that contains @list.
+ * @list must point to the field containing a pointer to the list, not the list directly
+ * the memory allocated for this list is tracked for the section and freed automatically
+ */
+extern int ucimap_resize_list(struct ucimap_section_data *sd, struct ucimap_list **list, int items);
+
+/**
+ * ucimap_free_item: free the allocated memory for a data structure member
+ * @sd: pointer to the ucimap section data
+ * @item: pointer to the field inside the data structure
+ *
+ * @sd must point to the data structure that contains @item.
+ * @item must point to the field containing a pointer to the allocated item
+ */
+extern void ucimap_free_item(struct ucimap_section_data *sd, void *item);
+
 #endif