marshal.h

   1 /*
   2  * marshal.h - SKS compatible marshalling routines
   3  *
   4  * Copyright 2011 Jonathan McDowell <noodles@earth.li>
   5  *
   6  * This program 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 Free
   8  * Software Foundation; version 2 of the License.
   9  *
  10  * This program is distributed in the hope that it will be useful, but WITHOUT
  11  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  12  * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
  13  * more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along with
  16  * this program; if not, write to the Free Software Foundation, Inc., 51
  17  * Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  */
  19
  20 #ifndef __MARSHAL_H__
  21 #define __MARSHAL_H__
  22
  23 #include "keyid.h"
  24 #include "keystructs.h"
  25
  26 /**
  27  *      marshal_publickey - Output an OpenPGP key as a byte stream
  28  *      @putchar_func: The function to put the next character to the stream
  29  *      @ctx: A pointer to the context structure for putchar_func.
  30  *      @key: The key to output.
  31  *
  32  *      Takes an OpenPGP key and marshals it to a byte stream - writes
  33  *      a 32 bit size of the forthcoming data in network byte order and
  34  *      then the flattened byte representation of the key.
  35  */
  36 void marshal_publickey(int (*putchar_func)(void *ctx, size_t count,
  37                                 void *c),
  38                                 void *ctx,
  39                                 const struct openpgp_publickey *key);
  40
  41 /**
  42  *      unmarshal_publickey - Turn a byte stream into an OpenPGP key
  43  *      @getchar_func: The function to get the next character from the stream
  44  *      @ctx: A pointer to the context structure for getchar_func.
  45  *
  46  *      Returns an OpenPGP structure which is the unmarshalled result of
  47  *      the input byte stream - ie the inverse of marshal_publickey.
  48  */
  49 struct openpgp_publickey *unmarshal_publickey(int (*getchar_func)(void *ctx,
  50                                 size_t count,
  51                                 void *c),
  52                                 void *ctx);
  53
  54 /**
  55  *      marshal_skshash - Output an SKS hash as a byte stream
  56  *      @putchar_func: The function to put the next character to the stream
  57  *      @ctx: A pointer to the context structure for putchar_func.
  58  *      @hash: The hash to output.
  59  *
  60  *      Takes an SKS hash and marshals it to a byte stream - writes
  61  *      a 32 bit size of the forthcoming data (16 bytes) in network byte order
  62  *      and then the byte representation of the hash.
  63  */
  64 void marshal_skshash(int (*putchar_func)(void *ctx, size_t count,
  65                                 void *c),
  66                                 void *ctx,
  67                                 const struct skshash *hash);
  68
  69 /**
  70  *      unmarshal_skshash - Turn a byte stream into an SKS hash structure
  71  *      @getchar_func: The function to get the next character from the stream
  72  *      @ctx: A pointer to the context structure for getchar_func.
  73  *
  74  *      Returns an SKS hash structure which is the unmarshalled result of
  75  *      the input byte stream - ie the inverse of marshal_skshash.
  76  */
  77 struct skshash *unmarshal_skshash(int (*getchar_func)(void *ctx, size_t count,
  78                                 void *c),
  79                                 void *ctx);
  80
  81 /**
  82  *      marshal_string - Output a string as a byte stream
  83  *      @putchar_func: The function to put the next character to the stream
  84  *      @ctx: A pointer to the context structure for putchar_func.
  85  *      @string: The string to output.
  86  *
  87  *      Takes a string and marshals it to a byte stream - writes a 32 bit size
  88  *      of the forthcoming data in network byte order and then the string.
  89  */
  90 void marshal_string(int (*putchar_func)(void *ctx, size_t count,
  91                                 void *c),
  92                                 void *ctx,
  93                                 const char *string);
  94
  95 /**
  96  *      unmarshal_string - Turn a byte stream into a string
  97  *      @getchar_func: The function to get the next character from the stream
  98  *      @ctx: A pointer to the context structure for getchar_func.
  99  *
 100  *      Returns a string which is the unmarshalled result of the input byte
 101  *      stream - ie the inverse of marshal_string.
 102  */
 103 char *unmarshal_string(int (*getchar_func)(void *ctx, size_t count,
 104                                 void *c),
 105                                 void *ctx);
 106
 107 /**
 108  *      marshal_array - Outputs an array as a byte stream
 109  *      @putchar_func: The function to put the next character to the stream
 110  *      @ctx: A pointer to the context structure for putchar_func.
 111  *      @marshal_func: The function to use to marshal each array element.
 112  *      @array: A pointer to the array to marshal
 113  *      @size:: The number of elements in the array.
 114  *
 115  *      Takes an array and marshals it into a byte stream. Outputs a 32 bit
 116  *      count of the elements in the array in network byte order and then
 117  *      calls marshal_func for each element in the array to provide the
 118  *      marshalled contents.
 119  */
 120 void marshal_array(int (*putchar_func)(void *ctx, size_t count,
 121                                 void *c),
 122                                 void *ctx,
 123                                 void (*marshal_func)(int
 124                                         (*putchar_func)(void *ctx,
 125                                                 size_t count, void *c),
 126                                         void *ctx, const void *item),
 127                                 void **array,
 128                                 int size);
 129
 130 /**
 131  *      unmarshal_array - Turn a byte stream into an array of elements
 132  *      @getchar_func: The function to get the next character from the stream
 133  *      @ctx: A pointer to the context structure for getchar_func.
 134  *      @unmarshal_func: The function to use to unmarshal each array element.
 135  *      @size: A pointer to where to store the number of elements unmarshalled
 136  *
 137  *      Takes a byte stream and unmarshals it into an array of elements,
 138  *      as determined by the supplied unmarshal_func function. ie the reverse
 139  *      of marshal_array.
 140  */
 141 void **unmarshal_array(int (*getchar_func)(void *ctx, size_t count,
 142                                 void *c),
 143                                 void *ctx,
 144                                 void *(*unmarshal_func)(int
 145                                         (*getchar_func)(void *ctx,
 146                                                 size_t count, void *c),
 147                                         void *ctx),
 148                                 int *size);
 149
 150 #endif /* __MARSHAL_H__ */