lib/silccore/silcattrs.h

   1 /*
   2
   3   silcattrs.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* silccore/SILC Attribute Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * Implementation of the Attribute Payload that may be used to send and
  25  * retrieve user online precense information in the SILC network.  This
  26  * implements the draft-riikonen-precense-attrs draft.
  27  *
  28  ***/
  29
  30 #ifndef SILCATTRS_H
  31 #define SILCATTRS_H
  32
  33 /****s* silccore/SilcAttributesAPI/SilcAttributePayload
  34  *
  35  * NAME
  36  *
  37  *    typedef struct SilcAttributePayloadStruct *SilcAttributePayload;
  38  *
  39  * DESCRIPTION
  40  *
  41  *    This context is the actual Attribute Payload and is allocated
  42  *    by silc_attribute_payload_parse and given as attribute usually to
  43  *    all silc_attribute_payload_* functions.  It is freed by the
  44  *    silc_attribute_payload_free function.
  45  *
  46  ***/
  47 typedef struct SilcAttributePayloadStruct *SilcAttributePayload;
  48
  49 /****d* silccore/SilcAttributesAPI/SilcAttribute
  50  *
  51  * NAME
  52  *
  53  *    typedef unsigned char SilcAttribute;
  54  *
  55  * DESCRIPTION
  56  *
  57  *    The SilcAttribute type definition and the attributes. The attributes
  58  *    listed here are the official attributes defined in the internet
  59  *    draft.  They define the contents of the attribute payload and the
  60  *    type of the attribute.
  61  *
  62  * SOURCE
  63  */
  64 typedef unsigned char SilcAttribute;
  65
  66 /* All defined attributes.  See the specs for detailed information.  The
  67    comment is the structure or data type that must be used with the
  68    silc_attribute_get_object function to fetch parsed attribute. */
  69 #define SILC_ATTRIBUTE_NONE                     0
  70 #define SILC_ATTRIBUTE_USER_INFO                1
  71 #define SILC_ATTRIBUTE_SERVICE                  2 /* SilcAttributeObjService */
  72 #define SILC_ATTRIBUTE_STATUS_MOOD              3 /* SilcAttributeMood */
  73 #define SILC_ATTRIBUTE_STATUS_FREETEXT          4 /* char * (UTF-8 string) */
  74 #define SILC_ATTRIBUTE_STATUS_MESSAGE           5 /* SilcAttributeObjMime */
  75 #define SILC_ATTRIBUTE_PREFERRED_LANGUAGE       6 /* char * (UTF-8 string) */
  76 #define SILC_ATTRIBUTE_PREFERRED_CONTACT        7 /* SilcAttributeContact */
  77 #define SILC_ATTRIBUTE_TIMEZONE                 8 /* char * (UTF-8 string */
  78 #define SILC_ATTRIBUTE_GEOLOCATION              9 /* SilcAttributeObjGeo */
  79 #define SILC_ATTRIBUTE_DEVICE_INFO              10 /* SilcAttributeObjDevice */
  80 #define SILC_ATTRIBUTE_EXTENSION                11 /* SilcAttributeObjMime */
  81 #define SILC_ATTRIBUTE_USER_PUBLIC_KEY          12 /* SilcAttributeObjPk */
  82 #define SILC_ATTRIBUTE_SERVER_PUBLIC_KEY        13 /* SilcAttributeObjPk */
  83 #define SILC_ATTRIBUTE_USER_DIGITAL_SIGNATURE   14 /* SilcAttributeObjPk */
  84 #define SILC_ATTRIBUTE_SERVER_DIGITAL_SIGNATURE 15 /* SilcAttributeObjPk */
  85 /***/
  86
  87 /****d* silccore/SilcAttributesAPI/SilcAttributeFlags
  88  *
  89  * NAME
  90  *
  91  *    typedef unsigned char SilcAttributeFlags;
  92  *
  93  * DESCRIPTION
  94  *
  95  *    Attribute Payload flags defined by the specification.
  96  *
  97  * SOURCE
  98  */
  99 typedef unsigned char SilcAttributeFlags;
 100
 101 /* All defined flags */
 102 #define SILC_ATTRIBUTE_FLAG_NONE          0x00    /* No flags */
 103 #define SILC_ATTRIBUTE_FLAG_INVALID       0x01    /* Invalid attribute */
 104 #define SILC_ATTRIBUTE_FLAG_VALID         0x02    /* Valid attribute */
 105 /***/
 106
 107 /****d* silccore/SilcAttributesAPI/SilcAttributeMood
 108  *
 109  * NAME
 110  *
 111  *    typedef enum { ... } SilcAttributeMood;
 112  *
 113  * DESCRIPTION
 114  *
 115  *    The user mood indicators defined by the specification.  This is
 116  *    bit mask.
 117  *
 118  * SOURCE
 119  */
 120 typedef enum {
 121   SILC_ATTRIBUTE_MOOD_NORMAL      = 0x00000000,   /* normal mood */
 122   SILC_ATTRIBUTE_MOOD_HAPPY       = 0x00000001,   /* user feel happy */
 123   SILC_ATTRIBUTE_MOOD_SAD         = 0x00000002,   /* user feel sad */
 124   SILC_ATTRIBUTE_MOOD_ANGRY       = 0x00000004,   /* user feel angry */
 125   SILC_ATTRIBUTE_MOOD_JEALOUS     = 0x00000008,   /* user feel jealous */
 126   SILC_ATTRIBUTE_MOOD_ASHAMED     = 0x00000010,   /* user feel ashamed */
 127   SILC_ATTRIBUTE_MOOD_INVINCIBLE  = 0x00000020,   /* user feel invincible */
 128   SILC_ATTRIBUTE_MOOD_INLOVE      = 0x00000040,   /* user feel in love */
 129   SILC_ATTRIBUTE_MOOD_SLEEPY      = 0x00000080,   /* user feel sleepy */
 130   SILC_ATTRIBUTE_MOOD_BORED       = 0x00000100,   /* user feel bored */
 131   SILC_ATTRIBUTE_MOOD_EXCITED     = 0x00000200,   /* user feel exited */
 132   SILC_ATTRIBUTE_MOOD_ANXIOUS     = 0x00000400,   /* user feel anxious */
 133 } SilcAttributeMood;
 134 /***/
 135
 136 /****d* silccore/SilcAttributesAPI/SilcAttributeContact
 137  *
 138  * NAME
 139  *
 140  *    typedef enum { ... } SilcAttributeContact;
 141  *
 142  * DESCRIPTION
 143  *
 144  *    The defined preferred contact methods defined by the specification.
 145  *    This is bit mask.
 146  *
 147  * SOURCE
 148  */
 149 typedef enum {
 150   SILC_ATTRIBUTE_CONTACT_NONE    = 0x00000000,    /* no specific method */
 151   SILC_ATTRIBUTE_CONTACT_EMAIL   = 0x00000001,    /* email preferred */
 152   SILC_ATTRIBUTE_CONTACT_CALL    = 0x00000002,    /* phone call preferred */
 153   SILC_ATTRIBUTE_CONTACT_PAGE    = 0x00000004,    /* "paging" preferred */
 154   SILC_ATTRIBUTE_CONTACT_SMS     = 0x00000008,    /* SMS preferred */
 155   SILC_ATTRIBUTE_CONTACT_MMS     = 0x00000010,    /* MMS preferred */
 156   SILC_ATTRIBUTE_CONTACT_CHAT    = 0x00000020,    /* chatting preferred */
 157 } SilcAttributeContact;
 158 /***/
 159
 160 /****d* silccore/SilcAttributesAPI/SilcAttributeDevice
 161  *
 162  * NAME
 163  *
 164  *    typedef enum { ... } SilcAttributeDevice;
 165  *
 166  * DESCRIPTION
 167  *
 168  *    The defined device types defined by the specification.
 169  *
 170  * SOURCE
 171  */
 172 typedef enum {
 173   SILC_ATTRIBUTE_DEVICE_COMPUTER      = 0,        /* device is computer */
 174   SILC_ATTRIBUTE_DEVICE_MOBILE_PHONE  = 1,        /* device is mobile phone */
 175   SILC_ATTRIBUTE_DEVICE_PDA           = 2,        /* device is PDA */
 176   SILC_ATTRIBUTE_DEVICE_TERMINAL      = 3,        /* device is terminal */
 177 } SilcAttributeDevice;
 178 /***/
 179
 180 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_parse
 181  *
 182  * SYNOPSIS
 183  *
 184  *    SilcAttributePayload
 185  *    silc_attribute_payload_parse(const unsigned char *payload,
 186  *                                 SilcUInt32 payload_len);
 187  *
 188  * DESCRIPTION
 189  *
 190  *    Parses one attribute payload sent as argument and saves it to
 191  *    SilcAttributePayload context.  The new allocated context is returned.
 192  *
 193  ***/
 194 SilcAttributePayload
 195 silc_attribute_payload_parse(const unsigned char *payload,
 196                              SilcUInt32 payload_len);
 197
 198 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_encode
 199  *
 200  * SYNOPSIS
 201  *
 202  *    SilcBuffer silc_attribute_payload_encode(SilcAttribute attribute,
 203  *                                             SilcAttributeFlags flags,
 204  *                                             const unsigned char *data,
 205  *                                             SilcUInt32 data_len);
 206  *
 207  * DESCRIPTION
 208  *
 209  *    Encodes one attribute payload and returns allocated buffer.  The
 210  *    `attributes' is the attribute type with `flags' and the actual
 211  *    attribute data indicated by `data' and `data_len'.
 212  *
 213  ***/
 214 SilcBuffer silc_attribute_payload_encode(SilcAttribute attribute,
 215                                          SilcAttributeFlags flags,
 216                                          const unsigned char *data,
 217                                          SilcUInt32 data_len);
 218
 219 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_parse_list
 220  *
 221  * SYNOPSIS
 222  *
 223  *    SilcDList
 224  *    silc_attribute_payload_parse_list(const unsigned char *payload,
 225  *                                      SilcUInt32 payload_len);
 226  *
 227  * DESCRIPTION
 228  *
 229  *    Parses list of Attribute payloads returning list of payloads. This
 230  *    is equivalent to the silc_attribute_payload_parse except that the
 231  *    `buffer' now includes multiple Attribute Payloads one after the other.
 232  *    You can produce such a list with silc_attribute_payload_encode_list
 233  *    function.
 234  *
 235  ***/
 236 SilcDList silc_attribute_payload_parse_list(const unsigned char *payload,
 237                                             SilcUInt32 payload_len);
 238
 239 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_encode_list
 240  *
 241  * SYNOPSIS
 242  *
 243  *    SilcBuffer silc_attribute_payload_encode(SilcUInt32 num_attrs, ...);
 244  *
 245  * DESCRIPTION
 246  *
 247  *    Encodes a list of Attribute payloads.  The `num_attrs' indicates the
 248  *    number of attributes sent as argument.  The variable argument list
 249  *    sent as argument includes the attribute, attribute flags, attribute
 250  *    data and attribute data length.  One attribute is one of these
 251  *    { attribute, attribute flags, data and data length } arguments.
 252  *    Returns the attribute payloads in data buffer one after the other.
 253  *    You can parse such list with silc_attribute_payload_parse_list
 254  *    function.
 255  *
 256  ***/
 257 SilcBuffer silc_attribute_payload_encode_list(SilcUInt32 num_attrs, ...);
 258
 259 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_free
 260  *
 261  * SYNOPSIS
 262  *
 263  *    void silc_attribute_payload_free(SilcAttributePayload payload);
 264  *
 265  * DESCRIPTION
 266  *
 267  *    Frees the Attribute Payload and all data in it.
 268  *
 269  ***/
 270 void silc_attribute_payload_free(SilcAttributePayload payload);
 271
 272 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_list_free
 273  *
 274  * SYNOPSIS
 275  *
 276  *    void silc_attribute_payload_list_free(SilcDList list);
 277  *
 278  * DESCRIPTION
 279  *
 280  *    Frees list of Attribute Payloads and all data in them.
 281  *
 282  ***/
 283 void silc_attribute_payload_list_free(SilcDList list);
 284
 285 /****f* silccore/SilcAttributesAPI/silc_attribute_get_attribute
 286  *
 287  * SYNOPSIS
 288  *
 289  *    SilcAttribute silc_attribute_get_attribute(SilcAttributePayload payload);
 290  *
 291  * DESCRIPTION
 292  *
 293  *    Return the attribute type from the payload indicated by `payload'.
 294  *
 295  ***/
 296 SilcAttribute silc_attribute_get_attribute(SilcAttributePayload payload);
 297
 298 /****f* silccore/SilcAttributesAPI/silc_attribute_get_flags
 299  *
 300  * SYNOPSIS
 301  *
 302  *    SilcAttributeFlags
 303  *    silc_attribute_get_flags(SilcAttributePayload payload);
 304  *
 305  * DESCRIPTION
 306  *
 307  *    Return the attribute flags from the payload indicated by `payload'.
 308  *
 309  ***/
 310 SilcAttributeFlags silc_attribute_get_flags(SilcAttributePayload payload);
 311
 312 /****f* silccore/SilcAttributesAPI/silc_attribute_get_data
 313  *
 314  * SYNOPSIS
 315  *
 316  *    const unsigned char *
 317  *    silc_attribute_get_data(SilcAttributePayload payload,
 318  *                            SilcUInt32 *data_len);
 319  *
 320  * DESCRIPTION
 321  *
 322  *    Returns the attribute data from the payload indicated by the `payload'
 323  *    The caller must not free the returned data pointer.
 324  *
 325  ***/
 326 const unsigned char *silc_attribute_get_data(SilcAttributePayload payload,
 327                                              SilcUInt32 *data_len);
 328
 329 /* Object structures */
 330
 331 /****s* silccore/SilcAttributesAPI/SilcAttributesObjService
 332  *
 333  * NAME
 334  *
 335  *    typedef struct { ... } SilcAttributesObjService;
 336  *
 337  * DESCRIPTION
 338  *
 339  *    SILC_ATTRIBUTE_SERVICE type object structure.
 340  *
 341  * SOURCE
 342  */
 343 typedef struct {
 344   SilcUInt32 port;              /* IANA specified service port */
 345   char address[256];            /* service address */
 346   bool status;                  /* online status (TRUE present in service) */
 347 } SilcAttributeObjService;
 348 /***/
 349
 350 /****s* silccore/SilcAttributesAPI/SilcAttributesObjMime
 351  *
 352  * NAME
 353  *
 354  *    typedef struct { ... } SilcAttributesObjMime;
 355  *
 356  * DESCRIPTION
 357  *
 358  *    Data type for MIME object as attribute.  The data in the structure
 359  *    is valid as long as the payload structure is valid.
 360  *
 361  * SOURCE
 362  */
 363 typedef struct {
 364   const unsigned char *mime;    /* MIME buffer */
 365   SilcUInt32 mime_len;          /* length of the MIME buffer */
 366 } SilcAttributeObjMime;
 367 /***/
 368
 369 /****s* silccore/SilcAttributesAPI/SilcAttributesObjGeo
 370  *
 371  * NAME
 372  *
 373  *    typedef struct { ... } SilcAttributesObjGeo;
 374  *
 375  * DESCRIPTION
 376  *
 377  *    SILC_ATTRIBUTE_GEOLOCATION type object.  The caller must free the
 378  *    strings inside the structure.
 379  *
 380  * SOURCE
 381  */
 382 typedef struct {
 383   char *longitude;              /* Longitude */
 384   char *latitude;               /* Latitude */
 385   char *altitude;               /* Altitude */
 386   char *accuracy;               /* Accuracy in meters */
 387 } SilcAttributeObjGeo;
 388 /***/
 389
 390 /****s* silccore/SilcAttributesAPI/SilcAttributesObjDevice
 391  *
 392  * NAME
 393  *
 394  *    typedef struct { ... } SilcAttributesObjDevice;
 395  *
 396  * DESCRIPTION
 397  *
 398  *    SILC_ATTRIBUTE_DEVICE_INFO type object.  The caller must free the
 399  *    strings inside the structure.
 400  *
 401  * SOURCE
 402  */
 403 typedef struct {
 404   SilcAttributeDevice type;     /* device type */
 405   char *manufacturer;           /* manufacturer of the device */
 406   char *version;                /* device version string */
 407   char *model;                  /* device model string */
 408   char *language;               /* device language (ISO 639-2/T) */
 409 } SilcAttributeObjDevice;
 410 /***/
 411
 412 /****s* silccore/SilcAttributesAPI/SilcAttributesObjPk
 413  *
 414  * NAME
 415  *
 416  *    typedef struct { ... } SilcAttributesObjPk;
 417  *
 418  * DESCRIPTION
 419  *
 420  *    Data type for public key, certificate or digital signatures.  The
 421  *    caller must free the data inside the structure.
 422  *
 423  * SOURCE
 424  */
 425 typedef struct {
 426   char *type;                   /* public key/certificate type, NULL
 427                                    when contains digital signature. */
 428   unsigned char *data;          /* public key/cert/signature data. The
 429                                    encoding depends of the `type'. */
 430   SilcUInt32 data_len;          /* data length */
 431 } SilcAttributeObjPk;
 432 /***/
 433
 434 /****f* silccore/SilcAttributesAPI/silc_attribute_get_object
 435  *
 436  * SYNOPSIS
 437  *
 438  *    bool silc_attribute_get_object(SilcAttributePayload payload,
 439  *                                   SilcAttribute attribute,
 440  *                                   const void **object,
 441  *                                   SilcUInt32 object_size);
 442  *
 443  * DESCRIPTION
 444  *
 445  *    Returns the already parsed attribute object by the attribute type
 446  *    indicated by `attribute'.  Copies the data into the `object' which
 447  *    must be sent as argument (and must be of correct type and size).
 448  *    The `object_size' indicates the size of the `*object' sent.
 449  *    Returns TRUE if the `attribute' attribute was found and FALSE
 450  *    if such attribute is not present in the `payload', or the `object_size'
 451  *    is not sufficient.  See the definition of SilcAttribute for the
 452  *    list of attributes and the required object types for attributes.
 453  *
 454  ***/
 455 bool silc_attribute_get_object(SilcAttributePayload payload,
 456                                SilcAttribute attribute,
 457                                void **object, SilcUInt32 object_size);
 458
 459 #endif /* SILCATTRS_H */