5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2002 Pekka Riikonen
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.
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.
20 /****h* silccore/SILC Attribute Interface
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.
33 /****s* silccore/SilcAttributesAPI/SilcAttributePayload
37 * typedef struct SilcAttributePayloadStruct *SilcAttributePayload;
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.
47 typedef struct SilcAttributePayloadStruct *SilcAttributePayload;
49 /****d* silccore/SilcAttributesAPI/SilcAttribute
53 * typedef unsigned char SilcAttribute;
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.
64 typedef unsigned char SilcAttribute;
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 */
87 /****d* silccore/SilcAttributesAPI/SilcAttributeFlags
91 * typedef unsigned char SilcAttributeFlags;
95 * Attribute Payload flags defined by the specification.
99 typedef unsigned char SilcAttributeFlags;
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 */
107 /****d* silccore/SilcAttributesAPI/SilcAttributeMood
111 * typedef enum { ... } SilcAttributeMood;
115 * The user mood indicators defined by the specification. This is
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 */
136 /****d* silccore/SilcAttributesAPI/SilcAttributeContact
140 * typedef enum { ... } SilcAttributeContact;
144 * The defined preferred contact methods defined by the specification.
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;
160 /****d* silccore/SilcAttributesAPI/SilcAttributeDevice
164 * typedef enum { ... } SilcAttributeDevice;
168 * The defined device types defined by the specification.
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;
180 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_parse
184 * SilcAttributePayload
185 * silc_attribute_payload_parse(const unsigned char *payload,
186 * SilcUInt32 payload_len);
190 * Parses one attribute payload sent as argument and saves it to
191 * SilcAttributePayload context. The new allocated context is returned.
194 silc_attribute_payload_parse(const unsigned char *payload,
195 SilcUInt32 payload_len);
197 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_encode
201 * SilcBuffer silc_attribute_payload_encode(SilcAttribute attribute,
202 * SilcAttributeFlags flags,
203 * const unsigned char *data,
204 * SilcUInt32 data_len);
208 * Encodes one attribute payload and returns allocated buffer. The
209 * `attributes' is the attribute type with `flags' and the actual
210 * attribute data indicated by `data' and `data_len'.
213 SilcBuffer silc_attribute_payload_encode(SilcAttribute attribute,
214 SilcAttributeFlags flags,
215 const unsigned char *data,
216 SilcUInt32 data_len);
218 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_parse_list
223 * silc_attribute_payload_parse_list(const unsigned char *payload,
224 * SilcUInt32 payload_len);
228 * Parses list of Attribute payloads returning list of payloads. This
229 * is equivalent to the silc_attribute_payload_parse except that the
230 * `buffer' now includes multiple Attribute Payloads one after the other.
231 * You can produce such a list with silc_attribute_payload_encode_list
235 SilcDList silc_attribute_payload_parse_list(const unsigned char *payload,
236 SilcUInt32 payload_len);
238 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_encode_list
242 * SilcBuffer silc_attribute_payload_encode(SilcUInt32 num_attrs, ...);
246 * Encodes a list of Attribute payloads. The `num_attrs' indicates the
247 * number of attributes sent as argument. The variable argument list
248 * sent as argument includes the attribute, attribute flags, attribute
249 * data and attribute data length. One attribute is one of these
250 * { attribute, attribute flags, data and data length } arguments.
251 * Returns the attribute payloads in data buffer one after the other.
252 * You can parse such list with silc_attribute_payload_parse_list
256 SilcBuffer silc_attribute_payload_encode_list(SilcUInt32 num_attrs, ...);
258 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_free
262 * void silc_attribute_payload_free(SilcAttributePayload payload);
266 * Frees the Attribute Payload and all data in it.
269 void silc_attribute_payload_free(SilcAttributePayload payload);
271 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_list_free
275 * void silc_attribute_payload_list_free(SilcDList list);
279 * Frees list of Attribute Payloads and all data in them.
282 void silc_attribute_payload_list_free(SilcDList list);
284 /****f* silccore/SilcAttributesAPI/silc_attribute_get_attribute
288 * SilcAttribute silc_attribute_get_attribute(SilcAttributePayload payload);
292 * Return the attribute type from the payload indicated by `payload'.
295 SilcAttribute silc_attribute_get_attribute(SilcAttributePayload payload);
297 /****f* silccore/SilcAttributesAPI/silc_attribute_get_flags
302 * silc_attribute_get_flags(SilcAttributePayload payload);
306 * Return the attribute flags from the payload indicated by `payload'.
309 SilcAttributeFlags silc_attribute_get_flags(SilcAttributePayload payload);
311 /****f* silccore/SilcAttributesAPI/silc_attribute_get_data
315 * const unsigned char *
316 * silc_attribute_get_data(SilcAttributePayload payload,
317 * SilcUInt32 *data_len);
321 * Returns the attribute data from the payload indicated by the `payload'
322 * The caller must not free the returned data pointer.
325 const unsigned char *silc_attribute_get_data(SilcAttributePayload payload,
326 SilcUInt32 *data_len);
328 /* Object structures */
330 /****s* silccore/SilcAttributesAPI/SilcAttributesObjService
334 * typedef struct { ... } SilcAttributesObjService;
338 * SILC_ATTRIBUTE_SERVICE type object structure.
343 SilcUInt32 port; /* IANA specified service port */
344 char address[256]; /* service address */
345 bool status; /* online status (TRUE present in service) */
346 } SilcAttributeObjService;
349 /****s* silccore/SilcAttributesAPI/SilcAttributesObjMime
353 * typedef struct { ... } SilcAttributesObjMime;
357 * Data type for MIME object as attribute. Caller must free the
358 * MIME data buffer inside the structure.
363 unsigned char *mime; /* allocated MIME buffer */
364 SilcUInt32 mime_len; /* length of the allocated MIME buffer */
365 } SilcAttributeObjMime;
368 /****s* silccore/SilcAttributesAPI/SilcAttributesObjGeo
372 * typedef struct { ... } SilcAttributesObjGeo;
376 * SILC_ATTRIBUTE_GEOLOCATION type object. The caller must free the
377 * strings inside the structure.
382 char *longitude; /* Longitude */
383 char *latitude; /* Latitude */
384 char *altitude; /* Altitude */
385 char *accuracy; /* Accuracy in meters */
386 } SilcAttributeObjGeo;
389 /****s* silccore/SilcAttributesAPI/SilcAttributesObjDevice
393 * typedef struct { ... } SilcAttributesObjDevice;
397 * SILC_ATTRIBUTE_DEVICE_INFO type object. The caller must free the
398 * strings inside the structure.
403 SilcAttributeDevice type; /* device type */
404 char *manufacturer; /* manufacturer of the device */
405 char *version; /* device version string */
406 char *model; /* device model string */
407 char *language; /* device language (ISO 639-2/T) */
408 } SilcAttributeObjDevice;
411 /****s* silccore/SilcAttributesAPI/SilcAttributesObjPk
415 * typedef struct { ... } SilcAttributesObjPk;
419 * Data type for public key, certificate or digital signatures. The
420 * caller must free the data inside the structure.
425 char *type; /* public key/certificate type, NULL
426 when contains digital signature. */
427 unsigned char *data; /* public key/cert/signature data. The
428 encoding depends of the `type'. */
429 SilcUInt32 data_len; /* data length */
430 } SilcAttributeObjPk;
433 /****f* silccore/SilcAttributesAPI/silc_attribute_get_object
437 * bool silc_attribute_get_object(SilcAttributePayload payload,
438 * SilcAttribute attribute,
439 * const void **object,
440 * SilcUInt32 object_size);
444 * Returns the already parsed attribute object by the attribute type
445 * indicated by `attribute'. Copies the data into the `object' which
446 * must be sent as argument (and must be of correct type and size).
447 * The `object_size' indicates the size of the `*object' sent.
448 * Returns TRUE if the `attribute' attribute was found and FALSE
449 * if such attribute is not present in the `payload', or the `object_size'
450 * is not sufficient. See the definition of SilcAttribute for the
451 * list attributes and the required object types for attributes.
454 bool silc_attribute_get_object(SilcAttributePayload payload,
455 SilcAttribute attribute,
456 void **object, SilcUInt32 object_size);
458 #endif /* SILCATTRS_H */