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,
 104                                 int count, ...);
 105
 106 /**
 107  * Decode a CSV formatted string. The csv structure should have been
 108  * initialized (with the string). The function creates a LIST of records
 109  * (csv_record_t structure) where each record is in turn a LIST of fields
 110  * (csv_field_t structure). The record points to the string containing the
 111  * list of fields. Similarly, the field points to the field string.
 112  * NB: csv initialized for discrete buf , caller will pass inbuf
 113  */
 114 void csv_decode(csv_t *csv, char *inbuf);
 115
 116 /**
 117  * Dump all fields of a decoded CSV to stderr
 118  */
 119 void csv_dump(csv_t *csv);
 120
 121 /**
 122  * Total length of all characters encoded in the CSV.
 123  */
 124 int csvlen(csv_t *csv);
 125
 126 void csv_clean(csv_t *csv);
 127 void csv_free(csv_t *csv);
 128
 129 /**
 130  * Iterate through the records and fields of an encoded/decoded CSV.
 131  */
 132 csv_record_t *csv_record_iter(csv_t *csv);
 133 csv_record_t *csv_record_iter_next(csv_record_t *rec);
 134 char *csv_field_iter(csv_record_t *rec, csv_field_t **fld);
 135 char *csv_field_iter_next(csv_field_t **fld);
 136
 137 /**
 138  * Return the length of field
 139  */
 140 int csv_field_len(csv_field_t *fld);
 141
 142 /**
 143  * Checks to see if a record belongs to a csv
 144  */
 145 int csv_is_record_valid(csv_t *csv, csv_record_t *in_rec);
 146
 147 /**
 148  * concat two records in a csv
 149  * Returns the newly formed record which includes fields from rec1 and rec2
 150  * rec1 and rec2 are removed
 151  */
 152 csv_record_t *csv_concat_record(csv_t *csv, csv_record_t *rec1,
 153                                csv_record_t *rec2);
 154
 155 /**
 156  * Remove a record from csv
 157  * Only works when csv has discrete record bufs
 158  */
 159 void csv_remove_record(csv_t *csv, csv_record_t *rec);
 160
 161 /**
 162  * Insert a record into csv
 163  * Only works when csv has discrete record bufs
 164  */
 165 void csv_insert_record(csv_t *csv, csv_record_t *rec);
 166
 167 /**
 168  * append fields to a record
 169  * Only works when csv has discrete record bufs
 170  */
 171 csv_record_t *
 172 csv_append_record (csv_t *csv, csv_record_t *rec, int count, ...);
 173
 174 /**
 175  * Serialize contents of csv into string
 176  * Only works when csv has discrete record bufs
 177  */
 178 int csv_serialize(csv_t *csv, char *msgbuf, int msglen);
 179
 180 /**
 181  * Clone a record.
 182  * Only works when csv has discrete record bufs
 183  */
 184 void csv_clone_record (csv_t *csv, csv_record_t *in_rec, csv_record_t **out_rec);
 185
 186 /**
 187  * Return number of records
 188  */
 189 int csv_num_records (csv_t *csv);
 190
 191 #endif