lib/csv.h

   1 /* CSV
   2  * Copyright (C) 2013 Cumulus Networks, Inc.
   3  *
   4  * This file is part of Quagga.
   5  *
   6  * Quagga is free software; you can redistribute it and/or modify it
   7  * under the terms of the GNU General Public License as published by the
   8  * Free Software Foundation; either version 2, or (at your option) any
   9  * later version.
  10  *
  11  * Quagga is distributed in the hope that it will be useful, but
  12  * WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License along
  17  * with this program; see the file COPYING; if not, write to the Free Software
  18  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
  19  */
  20
  21 #ifndef __CSV_H__
  22 #define __CSV_H__
  23
  24 /*
  25  * CSV encoding and decoding routines.
  26  *
  27  * Example:
  28  * Encoding side:
  29  *
  30  *      csv_t *csv;
  31  *      csv_record_t *fstrec;
  32  *      csv_record_t *rec;
  33  *      char  buf[BUFSIZ];
  34  *
  35  *      csv = csv_init(csv, buf, BUFSIZ);
  36  *      ...
  37  *      fstrec = csv_encode(csv, 2, "hello", "world");
  38  *      rec = csv_encode(csv, 2, "foo", "bar");
  39  *      ...
  40  *      fstrec = csv_encode_record(csv, fstrec, 2, "HELLO", "WORLD");
  41  *      ...
  42  *      csv_clean(csv);
  43  *
  44  * Decoding side:
  45  *
  46  *      csv_t *csv;
  47  *      csv_record_t *rec;
  48  *      csv_field_t *fld;
  49  *      char  *rcvdbuf;
  50  *
  51  *      csv = csv_init(csv, rcvdbuf, BUFSIZ);
  52  *      ...
  53  *      csv_decode(csv);
  54  *      csv_dump(csv);
  55  *
  56  *      for (rec = csv_record_iter(csv); rec;
  57  *           rec = csv_record_iter_next(rec)) {
  58  *          ...
  59  *          for (str = csv_field_iter(rec, &fld); str;
  60  *               str = csv_field_iter_next(&fld)) {
  61  *              ...
  62  *          }
  63  *      }
  64  *      ...
  65  *      csv_clean(csv);
  66  */
  67 #include <stdio.h>
  68 #include <stdlib.h>
  69 #include <string.h>
  70 #include <stdarg.h>
  71 #include <sys/queue.h>
  72
  73 typedef struct _csv_field_t_ csv_field_t;
  74 typedef struct _csv_record_t_ csv_record_t;
  75 typedef struct _csv_t_ csv_t;
  76
  77 /**
  78  * Initialize the CSV structure (if necessary, allocate first). Point to
  79  * the passed string buffer.
  80  */
  81 csv_t *csv_init(csv_t *csv, char *buf, int buflen);
  82
  83 /**
  84  * Encode the variable list of arguments as CSV fields. The csv structure
  85  * should have been initialized (with the string buffer). The fields get
  86  * concatenated into the string.
  87  */
  88 csv_record_t *csv_encode(csv_t *csv, int count, ...);
  89
  90 /**
  91  * Encode the variable list arguments into an existing record, essentially
  92  * overwriting the record. No checking is done for consistency. The number
  93  * of fields should be the same as what was encoded and the length of each
  94  * field should also be the same as what was encoded before. The "rec"
  95  * parameter should be the same as what was returned from a previous call
  96  * to csv_encode().
  97  *
  98  * Useful for message encoding/decoding that get passed around between
  99  * processes/nodes - e.g. the message header record can be rewritten AFTER
 100  * encoding all other records, with new information such as total length.
 101  */
 102 csv_record_t *csv_encode_record(csv_t *csv, csv_record_t *rec, int count, ...);
 103
 104 /**
 105  * Decode a CSV formatted string. The csv structure should have been
 106  * initialized (with the string). The function creates a LIST of records
 107  * (csv_record_t structure) where each record is in turn a LIST of fields
 108  * (csv_field_t structure). The record points to the string containing the
 109  * list of fields. Similarly, the field points to the field string.
 110  * NB: csv initialized for discrete buf , caller will pass inbuf
 111  */
 112 void csv_decode(csv_t *csv, char *inbuf);
 113
 114 /**
 115  * Dump all fields of a decoded CSV to stderr
 116  */
 117 void csv_dump(csv_t *csv);
 118
 119 /**
 120  * Total length of all characters encoded in the CSV.
 121  */
 122 int csvlen(csv_t *csv);
 123
 124 void csv_clean(csv_t *csv);
 125 void csv_free(csv_t *csv);
 126
 127 /**
 128  * Iterate through the records and fields of an encoded/decoded CSV.
 129  */
 130 csv_record_t *csv_record_iter(csv_t *csv);
 131 csv_record_t *csv_record_iter_next(csv_record_t *rec);
 132 char *csv_field_iter(csv_record_t *rec, csv_field_t **fld);
 133 char *csv_field_iter_next(csv_field_t **fld);
 134
 135 /**
 136  * Return the length of field
 137  */
 138 int csv_field_len(csv_field_t *fld);
 139
 140 /**
 141  * Checks to see if a record belongs to a csv
 142  */
 143 int csv_is_record_valid(csv_t *csv, csv_record_t *in_rec);
 144
 145 /**
 146  * concat two records in a csv
 147  * Returns the newly formed record which includes fields from rec1 and rec2
 148  * rec1 and rec2 are removed
 149  */
 150 csv_record_t *csv_concat_record(csv_t *csv, csv_record_t *rec1,
 151                                 csv_record_t *rec2);
 152
 153 /**
 154  * Remove a record from csv
 155  * Only works when csv has discrete record bufs
 156  */
 157 void csv_remove_record(csv_t *csv, csv_record_t *rec);
 158
 159 /**
 160  * Insert a record into csv
 161  * Only works when csv has discrete record bufs
 162  */
 163 void csv_insert_record(csv_t *csv, csv_record_t *rec);
 164
 165 /**
 166  * append fields to a record
 167  * Only works when csv has discrete record bufs
 168  */
 169 csv_record_t *csv_append_record(csv_t *csv, csv_record_t *rec, int count, ...);
 170
 171 /**
 172  * Serialize contents of csv into string
 173  * Only works when csv has discrete record bufs
 174  */
 175 int csv_serialize(csv_t *csv, char *msgbuf, int msglen);
 176
 177 /**
 178  * Clone a record.
 179  * Only works when csv has discrete record bufs
 180  */
 181 void csv_clone_record(csv_t *csv, csv_record_t *in_rec, csv_record_t **out_rec);
 182
 183 /**
 184  * Return number of records
 185  */
 186 int csv_num_records(csv_t *csv);
 187
 188 #endif