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 other the
  27  * information are not needed in context of SILC.  If such VCard is
  28  * received this 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 */
  63   char *org_unit;           /* organization unit */
  64   char *categories;         /* application category, string */
  65   char *class;              /* 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 *tel;              /* 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 } SilcVCardStruct, *SilcVCard;
 100 /***/
 101
 102 /****f* silcutil/SilcVCard/silc_vcard_encode
 103  *
 104  * SYNOPSIS
 105  *
 106  *    char *silc_vcard_encode(SilcVCard vcard, SilcUInt8 *vcard_len);
 107  *
 108  * DESCRIPTION
 109  *
 110  *    Encodes VCard from the SilcVCard structure indicated by `vcard'
 111  *    which the caller must fill before calling this function.  This
 112  *    function encodes the card and returns allocated buffer and
 113  *    its length into `vcard_len'.  The caller must free the returned
 114  *    buffer.  Returns NULL on error.
 115  *
 116  ***/
 117 char *silc_vcard_encode(SilcVCard vcard, SilcUInt32 *vcard_len);
 118
 119 /****f* silcutil/SilcVCard/silc_vcard_decode
 120  *
 121  * SYNOPSIS
 122  *
 123  *    bool silc_vcard_decode(const unsigned char *data, SilcUInt32 data_len,
 124  *                           SilcVCard vcard);
 125  *
 126  * DESCRIPTION
 127  *
 128  *    Decodes VCard from the buffer `vcard' of length of `vcard_len' bytes
 129  *    and returns the parsed card into `vcard' structure.  The caller must
 130  *    pre-allocate the structure.  Returns TRUE if the `vcard' is valid
 131  *    vcard and was successfully parsed or FALSE on error.  The structure
 132  *    is freed with silc_vcard_free function when it is not needed anymore.
 133  *
 134  ***/
 135 bool silc_vcard_decode(const unsigned char *data, SilcUInt32 data_len,
 136                        SilcVCard vcard);
 137
 138 /****f* silcutil/SilcVCard/silc_vcard_free
 139  *
 140  * SYNOPSIS
 141  *
 142  *    void silc_vcard_free(SilcVcard vcard);
 143  *
 144  * DESCRIPTION
 145  *
 146  *    Free VCard structure and all data in it.
 147  *
 148  ***/
 149 void silc_vcard_free(SilcVCard vcard);
 150
 151 /****f* silcutil/SilcVCard/silc_vcard_fprintf
 152  *
 153  * SYNOPSIS
 154  *
 155  *    void silc_vcard_fprintf(SilcVCard vcard, FILE *stream);
 156  *
 157  * DESCRIPTION
 158  *
 159  *    Prints the contents of the `vcard' into file stream `stream' in
 160  *    the correct VCard format.
 161  *
 162  ***/
 163 void silc_vcard_fprintf(SilcVCard vcard, FILE *stream);
 164
 165 #endif /* SILCVCARD_H */