Merge branch 'topic/mm-fixes' of git://208.110.73.182/silc into silc.1.1.branch

[silc.git] / lib / silcasn1 / silcasn1.h

diff --git a/lib/silcasn1/silcasn1.h b/lib/silcasn1/silcasn1.h
index 57c31905b9108e8285452b57a3c9f13a3275e495..df5bde14dab3319be604476d40de1647c15985f5 100644 (file)
--- a/lib/silcasn1/silcasn1.h
+++ b/lib/silcasn1/silcasn1.h
@@ -4,7 +4,7 @@
 
   Author: Pekka Riikonen <priikone@silcnet.org>
 
-  Copyright (C) 2003 - 2005 Pekka Riikonen
+  Copyright (C) 2003 - 2007 Pekka Riikonen
 
   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
@@ -35,7 +35,7 @@
  * pre-allocated SilcStack is used as memory.
  *
  * The encoding and decoding interface is simple.  silc_asn1_encode is used
- * encode and silc_asn1_decode to decode.  The actual ASN.1 is defined
+ * to encode and silc_asn1_decode to decode.  The actual ASN.1 is defined
  * as variable argument list to the function.  Various macros can be used
  * to encode and decode different ASN.1 types.  All types may also be used
  * to encode and decode with various options (such as implicit and explicit
@@ -102,6 +102,16 @@ typedef struct SilcAsn1Object SilcAsn1Struct;
  *    with SILC_ASN1_OPTS macro.  Other options can be given with various
  *    SILC_ASN1_*_T macros.
  *
+ * EXAMPLE
+ *
+ *    // Encodes boolean value with explicit tag and private class, and
+ *    // the result is allocated into `dest'.
+ *    silc_asn1_encode(asn1, &dest,
+ *                     SILC_ASN1_OPTS(SILC_ASN1_ALLOC),
+ *                     SILC_ASN1_BOOLEAN_T(SILC_ASN1_PRIVATE |
+ *                                         SILC_ASN1_EXPLICIT, 100, boolval),
+ *                     SILC_ASN1_END);
+ *
  * SOURCE
  */
 typedef enum {
@@ -413,7 +423,7 @@ SilcBool silc_asn1_decode(SilcAsn1 asn1, SilcBuffer src, ...);
  *
  *    Decoding:
  *    SILC_ASN1_ANY(&buffer)
- *    SILC_ASN1_ANY_T(opts, tag, &buffer)
+ *    SILC_ASN1_ANY_T(opts, tag, buffer)
  *
  * DESCRIPTION
  *
@@ -453,7 +463,7 @@ SilcBool silc_asn1_decode(SilcAsn1 asn1, SilcBuffer src, ...);
  *
  *    Decoding:
  *    SILC_ASN1_ANY_PRIMITIVE(tag, &buffer)
- *    SILC_ASN1_ANY_PRIMITIVE_T(opts, tag, &buffer)
+ *    SILC_ASN1_ANY_PRIMITIVE_T(opts, tag, buffer)
  *
  * DESCRIPTION
  *
@@ -656,7 +666,7 @@ SilcBool silc_asn1_decode(SilcAsn1 asn1, SilcBuffer src, ...);
  *
  * DESCRIPTION
  *
- *    Macro used to encode or decode boolean value.  Type boolean type
+ *    Macro used to encode or decode boolean value.  The boolean type
  *    is SilcBool.
  *
  *    The `opts' is SilcAsn1Options.  The `tag' is a tag number.
@@ -671,7 +681,7 @@ SilcBool silc_asn1_decode(SilcAsn1 asn1, SilcBuffer src, ...);
  *
  *    Encoding:
  *    SILC_ASN1_INT(integer)
- *    SILC_ASN1_INT_T(opts, tag, integer)
+ *    SILC_ASN1_INT_T(opts, tag, &integer)
  *
  *    Decoding:
  *    SILC_ASN1_INT(&integer)
@@ -688,13 +698,36 @@ SilcBool silc_asn1_decode(SilcAsn1 asn1, SilcBuffer src, ...);
 #define SILC_ASN1_INT(x) SILC_ASN1_U1(INTEGER, x)
 #define SILC_ASN1_INT_T(o, t, x) SILC_ASN1_T1(INTEGER, o, t, x)
 
+/****f* silcasn1/SilcASN1API/SILC_ASN1_SHORT_INT
+ *
+ * SYNOPSIS
+ *
+ *    Encoding:
+ *    SILC_ASN1_SHORT_INT(integer)
+ *    SILC_ASN1_SHORT_INT_T(opts, tag, &integer)
+ *
+ *    Decoding:
+ *    SILC_ASN1_SHORT_INT(&integer)
+ *    SILC_ASN1_SHORT_INT_T(opts, tag, &integer);
+ *
+ * DESCRIPTION
+ *
+ *    Macro used to encode or decode short integer (32 bits).  The
+ *    integer type is SilcUInt32.
+ *
+ *    The `opts' is SilcAsn1Options.  The `tag' is a tag number.
+ *
+ ***/
+#define SILC_ASN1_SHORT_INT(x) SILC_ASN1_U1(SHORT_INTEGER, x)
+#define SILC_ASN1_SHORT_INT_T(o, t, x) SILC_ASN1_T1(SHORT_INTEGER, o, t, x)
+
 /****f* silcasn1/SilcASN1API/SILC_ASN1_ENUM
  *
  * SYNOPSIS
  *
  *    Encoding:
  *    SILC_ASN1_ENUM(enum)
- *    SILC_ASN1_ENUM_T(opts, tag, enum)
+ *    SILC_ASN1_ENUM_T(opts, tag, &enum)
  *
  *    Decoding:
  *    SILC_ASN1_ENUM(&enum)
@@ -796,16 +829,11 @@ SilcBool silc_asn1_decode(SilcAsn1 asn1, SilcBuffer src, ...);
  * DESCRIPTION
  *
  *    Macro used to encode or decode octet string.  The string type is
- *    unsigned char and string length SilcUInt32.
+ *    unsigned char and string length SilcUInt32.  Octet string is
+ *    considered to be 8-bit unsigned binary data.
  *
  *    The `opts' is SilcAsn1Options.  The `tag' is a tag number.
  *
- * NOTES
- *
- *    The string must be in UTF-8 encoding when encoding.  The decoded
- *    string will be in UTF-8 encoding.  The actual data is encoded to
- *    or decoded from 8-bit ASCII.
- *
  ***/
 #define SILC_ASN1_OCTET_STRING(x, xl) SILC_ASN1_U2(OCTET_STRING, x, xl)
 #define SILC_ASN1_OCTET_STRING_T(o, t, x, xl) SILC_ASN1_T2(OCTET_STRING, o, t, x, xl)
@@ -1110,7 +1138,7 @@ SilcBool silc_asn1_decode(SilcAsn1 asn1, SilcBuffer src, ...);
  *
  *    Decoding:
  *    SILC_ASN1_UTC_TIME(&str, &timeval)
- *    SILC_ASN1_UTC_TIME_T(opts, tag, &timeval)
+ *    SILC_ASN1_UTC_TIME_T(opts, tag, timeval)
  *
  * DESCRIPTION
  *
@@ -1133,7 +1161,7 @@ SilcBool silc_asn1_decode(SilcAsn1 asn1, SilcBuffer src, ...);
  *
  *    Decoding:
  *    SILC_ASN1_GEN_TIME(&str, &timeval)
- *    SILC_ASN1_GEN_TIME_T(opts, tag, &timeval)
+ *    SILC_ASN1_GEN_TIME_T(opts, tag, timeval)
  *
  * DESCRIPTION
  *