lib/silcutil/silcvcard.h

   1 /*
   2
   3   silcvcard.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2002 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 /****h* silcutil/SILC VCard
  21  *
  22  * DESCRIPTION
  23  *
  24  * Implementation of the VCard 3.0 standard (RFC 2426) that can be used
  25  * with Requested Attributes (in WHOIS command) to deliver personal
  26  * information.  All fields are not supported since some of the
  27  * information are not needed in context of SILC.  If such VCard is
  28  * received this implementation ignores the unsupported fields.
  29  *
  30  ***/
  31
  32 #ifndef SILCVCARD_H
  33 #define SILCVCARD_H
  34
  35 /****s* silcutil/SilcVCard/SilcVCard
  36  *
  37  * NAME
  38  *
  39  *    typedef struct { ... } SilcVCardStruct, *SilcVCard;
  40  *
  41  * DESCRIPTION
  42  *
  43  *    This structure is the VCard.  This holds the contents of the
  44  *    card.  When a card is parsed it is parsed into this structure.
  45  *    When creating a new card application fills this structure and
  46  *    the library encodes the card from it.  Free the allocated
  47  *    structure with silc_vcard_free function.
  48  *
  49  * SOURCE
  50  */
  51 typedef struct {
  52   char *full_name;          /* full name, X.520 common name */
  53   char *family_name;        /* last name, string */
  54   char *first_name;         /* first name, string */
  55   char *middle_names;       /* other names, string (comma sep.) */
  56   char *prefix;             /* honorifix prefix (Mr., Mrs.), string */
  57   char *suffix;             /* honorifix suffix (MD), string (comma sep.) */
  58   char *nickname;           /* string (comma sep. if more than one) */
  59   char *bday;               /* birth day, UTC date string */
  60   char *title;              /* job title X.520, string */
  61   char *role;               /* job role X.520, string */
  62   char *org_name;           /* organization name, string */
  63   char *org_unit;           /* organization unit, string */
  64   char *categories;         /* application category, string */
  65   char *catclass;           /* class (public, private, confidental), string */
  66   char *url;                /* home page, URI string */
  67   char *label;              /* formatted address label, string (same
  68                                format as for 'addr' but comma sep.) */
  69
  70   struct addr {
  71     char *type;             /* address type, string
  72                                (intl, dom, home, work, pref, postal, parcel) */
  73     char *pbox;             /* post office box, string */
  74     char *ext_addr;         /* extended address, string */
  75     char *street_addr;      /* street address, string */
  76     char *city;             /* city, string */
  77     char *state;            /* state/province, string */
  78     char *code;             /* postal code, string */
  79     char *country;          /* country name, string */
  80   } *addrs;
  81   SilcUInt8 num_addrs;      /* number of addresses */
  82
  83   struct tel {
  84     char *type;             /* telephone number type, string
  85                                (msg, voice, home, work, pref, bbs, modem, car,
  86                                cell, video, pager, isdn, fax) */
  87     char *telnum;           /* single telephone number, string */
  88   } *tels;
  89   SilcUInt8 num_tels;
  90
  91   struct email {
  92     char *type;             /* email type, string (internet, pref, x400) */
  93     char *address;          /* single email address, string */
  94   } *emails;
  95   SilcUInt8 num_emails;
  96
  97   char *note;               /* a note, string */
  98   char *rev;                /* revision of card, UTC date string */
  99
 100   bool dynamic;             /* TRUE when dynamically allocated */
 101 } SilcVCardStruct, *SilcVCard;
 102 /***/
 103
 104 /****f* silcutil/SilcVCard/silc_vcard_encode
 105  *
 106  * SYNOPSIS
 107  *
 108  *    char *silc_vcard_encode(SilcVCard vcard, SilcUInt32 *vcard_len);
 109  *
 110  * DESCRIPTION
 111  *
 112  *    Encodes VCard from the SilcVCard structure indicated by `vcard'
 113  *    which the caller must fill before calling this function.  This
 114  *    function encodes the card and returns allocated buffer and
 115  *    its length into `vcard_len'.  The caller must free the returned
 116  *    buffer.  Returns NULL on error.
 117  *
 118  ***/
 119 unsigned char *silc_vcard_encode(SilcVCard vcard, SilcUInt32 *vcard_len);
 120
 121 /****f* silcutil/SilcVCard/silc_vcard_decode
 122  *
 123  * SYNOPSIS
 124  *
 125  *    bool silc_vcard_decode(const unsigned char *data, SilcUInt32 data_len,
 126  *                           SilcVCard vcard);
 127  *
 128  * DESCRIPTION
 129  *
 130  *    Decodes VCard from the buffer `vcard' of length of `vcard_len' bytes
 131  *    and returns the parsed card into `vcard' structure.  The caller must
 132  *    pre-allocate the structure.  Returns TRUE if the `vcard' is valid
 133  *    vcard and was successfully parsed or FALSE on error.  The structure
 134  *    is freed with silc_vcard_free function when it is not needed anymore.
 135  *
 136  ***/
 137 bool silc_vcard_decode(const unsigned char *data, SilcUInt32 data_len,
 138                        SilcVCard vcard);
 139
 140 /****f* silcutil/SilcVCard/silc_vcard_alloc
 141  *
 142  * SYNOPSIS
 143  *
 144  *    SilcVCard silc_vcard_alloc(void);
 145  *
 146  * DESCRIPTION
 147  *
 148  *    Allocate a SilcVCard context which must be freed with the
 149  *    silc_vcard_free function.
 150  *
 151  ***/
 152 SilcVCard silc_vcard_alloc(void);
 153
 154 /****f* silcutil/SilcVCard/silc_vcard_free
 155  *
 156  * SYNOPSIS
 157  *
 158  *    void silc_vcard_free(SilcVCard vcard);
 159  *
 160  * DESCRIPTION
 161  *
 162  *    Free VCard structure and all data in it.
 163  *
 164  ***/
 165 void silc_vcard_free(SilcVCard vcard);
 166
 167 /****f* silcutil/SilcVCard/silc_vcard_fprintf
 168  *
 169  * SYNOPSIS
 170  *
 171  *    void silc_vcard_fprintf(SilcVCard vcard, FILE *stream);
 172  *
 173  * DESCRIPTION
 174  *
 175  *    Prints the contents of the `vcard' into file stream `stream' in
 176  *    the correct VCard format.
 177  *
 178  ***/
 179 void silc_vcard_fprintf(SilcVCard vcard, FILE *stream);
 180
 181 #endif /* SILCVCARD_H */