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