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 SilcUInt8 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 SilcUInt8 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 /* SilcVCard */
  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 /* Maximum length of attribute request packet */
  88 #define SILC_ATTRIBUTE_MAX_REQUEST_LEN (4 * 255)
  89
  90 /****d* silccore/SilcAttributesAPI/SilcAttributeFlags
  91  *
  92  * NAME
  93  *
  94  *    typedef SilcUInt8 SilcAttributeFlags;
  95  *
  96  * DESCRIPTION
  97  *
  98  *    Attribute Payload flags defined by the specification.
  99  *
 100  * SOURCE
 101  */
 102 typedef SilcUInt8 SilcAttributeFlags;
 103
 104 /* All defined flags */
 105 #define SILC_ATTRIBUTE_FLAG_NONE          0x00    /* No flags */
 106 #define SILC_ATTRIBUTE_FLAG_INVALID       0x01    /* Invalid attribute */
 107 #define SILC_ATTRIBUTE_FLAG_VALID         0x02    /* Valid attribute */
 108 /***/
 109
 110 /****d* silccore/SilcAttributesAPI/SilcAttributeMood
 111  *
 112  * NAME
 113  *
 114  *    typedef enum { ... } SilcAttributeMood;
 115  *
 116  * DESCRIPTION
 117  *
 118  *    The user mood indicators defined by the specification.  This is
 119  *    bit mask.
 120  *
 121  * SOURCE
 122  */
 123 typedef enum {
 124   SILC_ATTRIBUTE_MOOD_NORMAL      = 0x00000000,   /* normal mood */
 125   SILC_ATTRIBUTE_MOOD_HAPPY       = 0x00000001,   /* user feel happy */
 126   SILC_ATTRIBUTE_MOOD_SAD         = 0x00000002,   /* user feel sad */
 127   SILC_ATTRIBUTE_MOOD_ANGRY       = 0x00000004,   /* user feel angry */
 128   SILC_ATTRIBUTE_MOOD_JEALOUS     = 0x00000008,   /* user feel jealous */
 129   SILC_ATTRIBUTE_MOOD_ASHAMED     = 0x00000010,   /* user feel ashamed */
 130   SILC_ATTRIBUTE_MOOD_INVINCIBLE  = 0x00000020,   /* user feel invincible */
 131   SILC_ATTRIBUTE_MOOD_INLOVE      = 0x00000040,   /* user feel in love */
 132   SILC_ATTRIBUTE_MOOD_SLEEPY      = 0x00000080,   /* user feel sleepy */
 133   SILC_ATTRIBUTE_MOOD_BORED       = 0x00000100,   /* user feel bored */
 134   SILC_ATTRIBUTE_MOOD_EXCITED     = 0x00000200,   /* user feel exited */
 135   SILC_ATTRIBUTE_MOOD_ANXIOUS     = 0x00000400,   /* user feel anxious */
 136 } SilcAttributeMood;
 137 /***/
 138
 139 /****d* silccore/SilcAttributesAPI/SilcAttributeContact
 140  *
 141  * NAME
 142  *
 143  *    typedef enum { ... } SilcAttributeContact;
 144  *
 145  * DESCRIPTION
 146  *
 147  *    The defined preferred contact methods defined by the specification.
 148  *    This is bit mask.
 149  *
 150  * SOURCE
 151  */
 152 typedef enum {
 153   SILC_ATTRIBUTE_CONTACT_NONE    = 0x00000000,    /* no specific method */
 154   SILC_ATTRIBUTE_CONTACT_EMAIL   = 0x00000001,    /* email preferred */
 155   SILC_ATTRIBUTE_CONTACT_CALL    = 0x00000002,    /* phone call preferred */
 156   SILC_ATTRIBUTE_CONTACT_PAGE    = 0x00000004,    /* "paging" preferred */
 157   SILC_ATTRIBUTE_CONTACT_SMS     = 0x00000008,    /* SMS preferred */
 158   SILC_ATTRIBUTE_CONTACT_MMS     = 0x00000010,    /* MMS preferred */
 159   SILC_ATTRIBUTE_CONTACT_CHAT    = 0x00000020,    /* chatting preferred */
 160 } SilcAttributeContact;
 161 /***/
 162
 163 /****d* silccore/SilcAttributesAPI/SilcAttributeDevice
 164  *
 165  * NAME
 166  *
 167  *    typedef enum { ... } SilcAttributeDevice;
 168  *
 169  * DESCRIPTION
 170  *
 171  *    The defined device types defined by the specification.
 172  *
 173  * SOURCE
 174  */
 175 typedef enum {
 176   SILC_ATTRIBUTE_DEVICE_COMPUTER      = 0,        /* device is computer */
 177   SILC_ATTRIBUTE_DEVICE_MOBILE_PHONE  = 1,        /* device is mobile phone */
 178   SILC_ATTRIBUTE_DEVICE_PDA           = 2,        /* device is PDA */
 179   SILC_ATTRIBUTE_DEVICE_TERMINAL      = 3,        /* device is terminal */
 180 } SilcAttributeDevice;
 181 /***/
 182
 183 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_alloc
 184  *
 185  * SYNOPSIS
 186  *
 187  *    SilcAttributesPayload
 188  *    silc_attribute_payload_alloc(SilcAttribute attribute,
 189  *                                 SilcAttributeFlags flags,
 190  *                                 void *object,
 191  *                                 SilcUInt32 object_size);
 192  *
 193  * DESCRIPTION
 194  *
 195  *    Allocates and encodes the attribute indicated by `attribute' and
 196  *    returns pointer to the attribute.
 197  *
 198  *    The `object' must always be the same data type as defined with
 199  *    SilcAttribute (see the comments) for all attributes.
 200  *
 201  ***/
 202 SilcAttributePayload silc_attribute_payload_alloc(SilcAttribute attribute,
 203                                                   SilcAttributeFlags flags,
 204                                                   void *object,
 205                                                   SilcUInt32 object_size);
 206
 207 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_parse
 208  *
 209  * SYNOPSIS
 210  *
 211  *    SilcDList
 212  *    silc_attribute_payload_parse(const unsigned char *payload,
 213  *                                 SilcUInt32 payload_len);
 214  *
 215  * DESCRIPTION
 216  *
 217  *    Parses list of Attribute payloads returning list of payloads.
 218  *    One entry in the returned list is SilcAttributesPayload.  You
 219  *    can produce such a list with silc_attribute_payload_encode
 220  *    function.
 221  *
 222  ***/
 223 SilcDList silc_attribute_payload_parse(const unsigned char *payload,
 224                                        SilcUInt32 payload_len);
 225
 226 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_encode
 227  *
 228  * SYNOPSIS
 229  *
 230  *    SilcBuffer silc_attribute_payload_encode(SilcBuffer attrs,
 231  *                                             SilcAttribute attribute,
 232  *                                             SilcAttributeFlags flags,
 233  *                                             void *object,
 234  *                                             SilcUInt32 object_size);
 235  *
 236  * DESCRIPTION
 237  *
 238  *    Encodes one attribute payload into the `attrs' buffer and returns
 239  *    pointer to the buffer, which may be different in case the buffer
 240  *    was reallocated.  If `attrs' is NULL for first attribute this
 241  *    allocates the buffer and returns it.  This can be called multiple
 242  *    times to add multiple attributes to the `attrs' buffer.  The `flags'
 243  *    indicates the validity of the added attribute.  Returns NULL on
 244  *    error.
 245  *
 246  *    The `object' must always be the same data type as defined with
 247  *    SilcAttribute (see the comments) for all attributes.
 248  *
 249  ***/
 250 SilcBuffer silc_attribute_payload_encode(SilcBuffer attrs,
 251                                          SilcAttribute attribute,
 252                                          SilcAttributeFlags flags,
 253                                          void *object,
 254                                          SilcUInt32 object_size);
 255
 256 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_encode_data
 257  *
 258  * SYNOPSIS
 259  *
 260  *    SilcBuffer
 261  *    silc_attribute_payload_encode_data(SilcBuffer attrs,
 262  *                                       SilcAttribute attribute,
 263  *                                       SilcAttributeFlags flags,
 264  *                                       const unsigned char *data,
 265  *                                       SilcUInt32 data_len);
 266  *
 267  * DESCRIPTION
 268  *
 269  *    Same function as silc_attribute_payload_encode except the attribute
 270  *    is already encoded into `data' of `data_len' bytes in length.
 271  *    Encodes the attribute into the `attrs' buffer and returns pointer
 272  *    to the buffer, which may be different in case the buffer was
 273  *    reallocated.  If `attrs' is NULL for first attribute this allocates
 274  *    the buffer and returns it.  Returns NULL on error.
 275  *
 276  ***/
 277 SilcBuffer silc_attribute_payload_encode_data(SilcBuffer attrs,
 278                                               SilcAttribute attribute,
 279                                               SilcAttributeFlags flags,
 280                                               const unsigned char *data,
 281                                               SilcUInt32 data_len);
 282
 283 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_free
 284  *
 285  * SYNOPSIS
 286  *
 287  *    void silc_attribute_payload_free(SilcAttributePayload payload);
 288  *
 289  * DESCRIPTION
 290  *
 291  *    Frees the Attribute Payload and all data in it.
 292  *
 293  ***/
 294 void silc_attribute_payload_free(SilcAttributePayload payload);
 295
 296 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_list_free
 297  *
 298  * SYNOPSIS
 299  *
 300  *    void silc_attribute_payload_list_free(SilcDList list);
 301  *
 302  * DESCRIPTION
 303  *
 304  *    Frees list of Attribute Payloads and all data in them.
 305  *
 306  ***/
 307 void silc_attribute_payload_list_free(SilcDList list);
 308
 309 /****f* silccore/SilcAttributesAPI/silc_attribute_get_attribute
 310  *
 311  * SYNOPSIS
 312  *
 313  *    SilcAttribute silc_attribute_get_attribute(SilcAttributePayload payload);
 314  *
 315  * DESCRIPTION
 316  *
 317  *    Return the attribute type from the payload indicated by `payload'.
 318  *
 319  ***/
 320 SilcAttribute silc_attribute_get_attribute(SilcAttributePayload payload);
 321
 322 /****f* silccore/SilcAttributesAPI/silc_attribute_get_flags
 323  *
 324  * SYNOPSIS
 325  *
 326  *    SilcAttributeFlags
 327  *    silc_attribute_get_flags(SilcAttributePayload payload);
 328  *
 329  * DESCRIPTION
 330  *
 331  *    Return the attribute flags from the payload indicated by `payload'.
 332  *
 333  ***/
 334 SilcAttributeFlags silc_attribute_get_flags(SilcAttributePayload payload);
 335
 336 /****f* silccore/SilcAttributesAPI/silc_attribute_get_data
 337  *
 338  * SYNOPSIS
 339  *
 340  *    const unsigned char *
 341  *    silc_attribute_get_data(SilcAttributePayload payload,
 342  *                            SilcUInt32 *data_len);
 343  *
 344  * DESCRIPTION
 345  *
 346  *    Returns the attribute data from the payload indicated by the `payload'
 347  *    The caller must not free the returned data pointer.
 348  *
 349  ***/
 350 const unsigned char *silc_attribute_get_data(SilcAttributePayload payload,
 351                                              SilcUInt32 *data_len);
 352
 353 /****f* silccore/SilcAttributesAPI/silc_attribute_get_verify_data
 354  *
 355  * SYNOPSIS
 356  *
 357  *    unsigned char *
 358  *    silc_attribute_get_verify_data(SilcDList attrs,
 359  *                                   bool server_verification,
 360  *                                   SilcUInt32 *data_len);
 361  *
 362  * DESCRIPTION
 363  *
 364  *    Constructs the data to be verified with the sender's digital
 365  *    signature and sender's public key.  This allocates the data from
 366  *    the list of attribute payloads and returns the buffer.  The caller
 367  *    must free it.  If `server_verification' is FALSE then data is
 368  *    constructed for user's digital signature verification, if it is
 369  *    TRUE then it is constructed for server's digital signature
 370  *    verification.
 371  *
 372  ***/
 373 unsigned char *silc_attribute_get_verify_data(SilcDList attrs,
 374                                               bool server_verification,
 375                                               SilcUInt32 *data_len);
 376
 377 /* Object structures */
 378
 379 /****s* silccore/SilcAttributesAPI/SilcAttributeObjService
 380  *
 381  * NAME
 382  *
 383  *    typedef struct { ... } SilcAttributeObjService;
 384  *
 385  * DESCRIPTION
 386  *
 387  *    SILC_ATTRIBUTE_SERVICE type object structure.
 388  *
 389  * SOURCE
 390  */
 391 typedef struct {
 392   SilcUInt32 port;              /* IANA specified service port */
 393   SilcUInt32 idle;              /* Idle time in the service */
 394   char signon[64];              /* Signon date and time (UTC) */
 395   char address[256];            /* service address */
 396   bool status;                  /* online status (TRUE present in service) */
 397 } SilcAttributeObjService;
 398 /***/
 399
 400 /****s* silccore/SilcAttributesAPI/SilcAttributeObjMime
 401  *
 402  * NAME
 403  *
 404  *    typedef struct { ... } SilcAttributeObjMime;
 405  *
 406  * DESCRIPTION
 407  *
 408  *    Data type for MIME object as attribute.  The data in the structure
 409  *    is valid as long as the payload structure is valid.
 410  *
 411  * SOURCE
 412  */
 413 typedef struct {
 414   const unsigned char *mime;    /* MIME buffer */
 415   SilcUInt32 mime_len;          /* length of the MIME buffer */
 416 } SilcAttributeObjMime;
 417 /***/
 418
 419 /****s* silccore/SilcAttributesAPI/SilcAttributeObjGeo
 420  *
 421  * NAME
 422  *
 423  *    typedef struct { ... } SilcAttributeObjGeo;
 424  *
 425  * DESCRIPTION
 426  *
 427  *    SILC_ATTRIBUTE_GEOLOCATION type object.  The caller must free the
 428  *    strings inside the structure.
 429  *
 430  * SOURCE
 431  */
 432 typedef struct {
 433   char *longitude;              /* Longitude */
 434   char *latitude;               /* Latitude */
 435   char *altitude;               /* Altitude */
 436   char *accuracy;               /* Accuracy in meters */
 437 } SilcAttributeObjGeo;
 438 /***/
 439
 440 /****s* silccore/SilcAttributesAPI/SilcAttributeObjDevice
 441  *
 442  * NAME
 443  *
 444  *    typedef struct { ... } SilcAttributeObjDevice;
 445  *
 446  * DESCRIPTION
 447  *
 448  *    SILC_ATTRIBUTE_DEVICE_INFO type object.  The caller must free the
 449  *    strings inside the structure.
 450  *
 451  * SOURCE
 452  */
 453 typedef struct {
 454   SilcAttributeDevice type;     /* device type */
 455   char *manufacturer;           /* manufacturer of the device */
 456   char *version;                /* device version string */
 457   char *model;                  /* device model string */
 458   char *language;               /* device language (ISO 639-2/T) */
 459 } SilcAttributeObjDevice;
 460 /***/
 461
 462 /****s* silccore/SilcAttributesAPI/SilcAttributeObjPk
 463  *
 464  * NAME
 465  *
 466  *    typedef struct { ... } SilcAttributeObjPk;
 467  *
 468  * DESCRIPTION
 469  *
 470  *    Data type for public key, certificate or digital signatures.  The
 471  *    caller must free the data inside the structure.
 472  *
 473  * SOURCE
 474  */
 475 typedef struct {
 476   char *type;                   /* public key/certificate type, NULL
 477                                    when contains digital signature. */
 478   unsigned char *data;          /* public key/cert/signature data. The
 479                                    encoding depends of the `type'. */
 480   SilcUInt32 data_len;          /* data length */
 481 } SilcAttributeObjPk;
 482 /***/
 483
 484 /****f* silccore/SilcAttributesAPI/silc_attribute_get_object
 485  *
 486  * SYNOPSIS
 487  *
 488  *    bool silc_attribute_get_object(SilcAttributePayload payload,
 489  *                                   void *object,
 490  *                                   SilcUInt32 object_size);
 491  *
 492  * DESCRIPTION
 493  *
 494  *    Returns the already parsed attribute object from the payload
 495  *    indicated by `payload'.  Copies the data into the `object' which
 496  *    must be sent as argument (and must be of correct type and size).
 497  *    The `object_size' indicates the size of the `*object' sent.
 498  *    Returns TRUE if the `attribute' attribute was found and FALSE
 499  *    if such attribute is not present in the `payload', or the `object_size'
 500  *    is not sufficient.  See the definition of SilcAttribute for the
 501  *    list of attributes and the required object types for attributes.
 502  *    You can use silc_attribute_get_attribute to get the SilcAttribute
 503  *    type from the `payload'.
 504  *
 505  ***/
 506 bool silc_attribute_get_object(SilcAttributePayload payload,
 507                                void *object, SilcUInt32 object_size);
 508
 509 #endif /* SILCATTRS_H */