common/name-value.h

   1 /* name-value.h - Parser and writer for a name-value format.
   2  *      Copyright (C) 2016 g10 Code GmbH
   3  *
   4  * This file is part of GnuPG.
   5  *
   6  * This file is free software; you can redistribute it and/or modify
   7  * it under the terms of either
   8  *
   9  *   - the GNU Lesser General Public License as published by the Free
  10  *     Software Foundation; either version 3 of the License, or (at
  11  *     your option) any later version.
  12  *
  13  * or
  14  *
  15  *   - the GNU General Public License as published by the Free
  16  *     Software Foundation; either version 2 of the License, or (at
  17  *     your option) any later version.
  18  *
  19  * or both in parallel, as here.
  20  *
  21  * GnuPG is distributed in the hope that it will be useful,
  22  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  23  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  24  * GNU General Public License for more details.
  25  *
  26  * You should have received a copy of the GNU General Public License
  27  * along with this program; if not, see <https://www.gnu.org/licenses/>.
  28  */
  29
  30 #ifndef GNUPG_COMMON_NAME_VALUE_H
  31 #define GNUPG_COMMON_NAME_VALUE_H
  32
  33 struct name_value_container;
  34 typedef struct name_value_container *nvc_t;
  35
  36 struct name_value_entry;
  37 typedef struct name_value_entry *nve_t;
  38
  39 \f
  40
  41 /* Memory management, and dealing with entries.  */
  42
  43 /* Allocate a name value container structure.  */
  44 nvc_t nvc_new (void);
  45
  46 /* Allocate a name value container structure for use with the extended
  47  * private key format.  */
  48 nvc_t nvc_new_private_key (void);
  49
  50 /* Release a name value container structure.  */
  51 void nvc_release (nvc_t pk);
  52
  53 /* Get the name.  */
  54 char *nve_name (nve_t pke);
  55
  56 /* Get the value.  */
  57 char *nve_value (nve_t pke);
  58
  59 \f
  60
  61 /* Lookup and iteration.  */
  62
  63 /* Get the first non-comment entry.  */
  64 nve_t nvc_first (nvc_t pk);
  65
  66 /* Get the first entry with the given name.  */
  67 nve_t nvc_lookup (nvc_t pk, const char *name);
  68
  69 /* Get the next non-comment entry.  */
  70 nve_t nve_next (nve_t entry);
  71
  72 /* Get the next entry with the given name.  */
  73 nve_t nve_next_value (nve_t entry, const char *name);
  74
  75 \f
  76
  77 /* Adding and modifying values.  */
  78
  79 /* Add (NAME, VALUE) to PK.  If an entry with NAME already exists, it
  80    is not updated but the new entry is appended.  */
  81 gpg_error_t nvc_add (nvc_t pk, const char *name, const char *value);
  82
  83 /* Add (NAME, VALUE) to PK.  If an entry with NAME already exists, it
  84    is updated with VALUE.  If multiple entries with NAME exist, the
  85    first entry is updated.  */
  86 gpg_error_t nvc_set (nvc_t pk, const char *name, const char *value);
  87
  88 /* Delete the given entry from PK.  */
  89 void nvc_delete (nvc_t pk, nve_t pke);
  90
  91 \f
  92
  93 /* Private key handling.  */
  94
  95 /* Get the private key.  */
  96 gpg_error_t nvc_get_private_key (nvc_t pk, gcry_sexp_t *retsexp);
  97
  98 /* Set the private key.  */
  99 gpg_error_t nvc_set_private_key (nvc_t pk, gcry_sexp_t sexp);
 100
 101 \f
 102
 103 /* Parsing and serialization.  */
 104
 105 /* Parse STREAM and return a newly allocated private key container
 106    structure in RESULT.  If ERRLINEP is given, the line number the
 107    parser was last considering is stored there.  */
 108 gpg_error_t nvc_parse (nvc_t *result, int *errlinep, estream_t stream);
 109
 110 /* Parse STREAM and return a newly allocated name value container
 111    structure in RESULT - assuming the extended private key format.  If
 112    ERRLINEP is given, the line number the parser was last considering
 113    is stored there.  */
 114 gpg_error_t nvc_parse_private_key (nvc_t *result, int *errlinep,
 115                                    estream_t stream);
 116
 117 /* Write a representation of PK to STREAM.  */
 118 gpg_error_t nvc_write (nvc_t pk, estream_t stream);
 119
 120 #endif /* GNUPG_COMMON_NAME_VALUE_H */