1.1 --- a/ucx/properties.h Wed Jul 24 14:26:17 2013 +0200
1.2 +++ b/ucx/properties.h Mon Aug 05 14:38:37 2013 +0200
1.3 @@ -25,6 +25,14 @@
1.4 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
1.5 * POSSIBILITY OF SUCH DAMAGE.
1.6 */
1.7 +/**
1.8 + * @file properties.h
1.9 + *
1.10 + * Load / store utilities for properties files.
1.11 + *
1.12 + * @author Mike Becker
1.13 + * @author Olaf Wintermann
1.14 + */
1.15
1.16 #ifndef UCX_PROPERTIES_H
1.17 #define UCX_PROPERTIES_H
1.18 @@ -51,13 +59,53 @@
1.19 } UcxProperties;
1.20
1.21
1.22 +/**
1.23 + * Constructs a new UcxProperties object.
1.24 + * @return A pointer to the new UcxProperties object.
1.25 + */
1.26 UcxProperties *ucx_properties_new();
1.27 -void ucx_properties_free(UcxProperties *parser);
1.28 -void ucx_properties_fill(UcxProperties *parser, char *buf, size_t len);
1.29 -int ucx_properties_next(UcxProperties *parser, sstr_t *name, sstr_t *value);
1.30 -int ucx_properties2map(UcxProperties *parser, UcxMap *map);
1.31 +/**
1.32 + * Destroys an UcxProperties object.
1.33 + * @param prop The UcxProperties object to destroy.
1.34 + */
1.35 +void ucx_properties_free(UcxProperties *prop);
1.36 +/**
1.37 + * Refills the input buffer.
1.38 + * @param prop The UcxProperties object.
1.39 + * @param buf A pointer to the new buffer.
1.40 + * @param len The payload length of the buffer.
1.41 + */
1.42 +void ucx_properties_fill(UcxProperties *prop, char *buf, size_t len);
1.43 +int ucx_properties_next(UcxProperties *prop, sstr_t *name, sstr_t *value);
1.44 +int ucx_properties2map(UcxProperties *prop, UcxMap *map);
1.45
1.46 +/**
1.47 + * Loads a properties file to an UcxMap.
1.48 + *
1.49 + * This is a convenience function that reads chunks of 1 KB from an input
1.50 + * stream until the end of the stream is reached.
1.51 + *
1.52 + * An UcxProperties object is implicitly created and destroyed.
1.53 + *
1.54 + * @param map The map object to write the key/value-pairs to.
1.55 + * @param file The <code>FILE*</code> stream to read from.
1.56 + * @return 0 on success, or a non-zero value on error
1.57 + *
1.58 + * @see ucx_properties_fill()
1.59 + * @see ucx_properties2map()
1.60 + */
1.61 int ucx_properties_load(UcxMap *map, FILE *file);
1.62 +/**
1.63 + * Stores an UcxMap to a file.
1.64 + *
1.65 + * The key/value-pairs are written by using the following format:
1.66 + *
1.67 + * <code>[key] = [value]\\n</code>
1.68 + *
1.69 + * @param map The map to store.
1.70 + * @param file The <code>FILE*</code> stream to write to.
1.71 + * @return 0 on success, or a non-zero value on error
1.72 + */
1.73 int ucx_properties_store(UcxMap *map, FILE *file);
1.74
1.75 #ifdef __cplusplus
