... generate_api
authornk
Tue, 05 Mar 2019 13:56:11 +0100
branchgenerate_api
changeset 3327e423895a97fa
parent 3311 cdfdb6831046
child 3328 c09e7d4bd944
...
api/basic_api.yml2
api/keymanagement_api.yml2
api/message_api.yml2
api/pEp.yml2
src/message.h
     1.1 --- a/api/basic_api.yml2	Fri Feb 22 12:59:32 2019 +0100
     1.2 +++ b/api/basic_api.yml2	Tue Mar 05 13:56:11 2019 +0100
     1.3 @@ -20,7 +20,25 @@
     1.4  type TID doc="UUID version 4 variant 1"
     1.5      is binary size=16;
     1.6  
     1.7 -type blob_list is list < blob >;
     1.8 +type blob_list is list< blob >;
     1.9 +
    1.10 +type identity_list is list< identity >;
    1.11 +
    1.12 +type string_list is list< string > ; 
    1.13 +
    1.14 +type string_pair is pair< string, string >;
    1.15 +
    1.16 +// string:  text
    1.17 +// int:     integer number
    1.18 +// blob:    Binary Large Object
    1.19 +// size_t:  size in memory
    1.20 +// const:
    1.21 +// identity:
    1.22 +// message:
    1.23 +// rating:
    1.24 +// enc_format:
    1.25 +// hash:
    1.26 +// TID:
    1.27  
    1.28  
    1.29  enum comm_type {
     2.1 --- a/api/keymanagement_api.yml2	Fri Feb 22 12:59:32 2019 +0100
     2.2 +++ b/api/keymanagement_api.yml2	Tue Mar 05 13:56:11 2019 +0100
     2.3 @@ -54,7 +54,7 @@
     2.4  			doc="""
     2.5  				if a default key was found for this identity, no
     2.6  				other acceptable keys were found; if this is returned,
     2.7 -				the reason for rejecting the first default key found
     2.8 +				the reason for rejecting the first default key found	
     2.9  				may be found in the comm_type
    2.10  				"""
    2.11  	}
     3.1 --- a/api/message_api.yml2	Fri Feb 22 12:59:32 2019 +0100
     3.2 +++ b/api/message_api.yml2	Tue Mar 05 13:56:11 2019 +0100
     3.3 @@ -30,15 +30,40 @@
     3.4  }
     3.5  
     3.6  
     3.7 +enum ratings {
     3.8 +    item rating_undefined 0;
     3.9 +    item rating_cannot_decrypt 1;
    3.10 +    item rating_have_no_key 2;
    3.11 +    item rating_unencrypted 3;
    3.12 +    item rating_unencrypted_for_some doc="don't use this any more",
    3.13 +    item rating_unreliable 4;
    3.14 +    item rating_reliable 5;
    3.15 +    item rating_trusted 6;
    3.16 +    item rating_trusted_and_anonymized 7;
    3.17 +    item rating_fully_anonymous 8;
    3.18 +    item rating_mistrust -1;
    3.19 +    item rating_b0rken -2;
    3.20 +    item rating_under_attack -3;
    3.21 +}
    3.22 +    
    3.23 +
    3.24 +enum colors {
    3.25 +        item color_no_color 0;
    3.26 +        item color_yellow 1;
    3.27 +        item color_green 2;
    3.28 +        item color_red -1;
    3.29 +}
    3.30 +
    3.31 +
    3.32  struct message {
    3.33 -field msg_direction dir;
    3.34 +    field msg_direction dir;
    3.35      field string id doc='string of message ID';
    3.36      field string shortmsg doc='string of short message';
    3.37 -    field string longmsg doc='string of long message'(plain)';
    3.38 +    field string longmsg doc='string of long message (plain)';
    3.39      field string longmsg_formatted doc='string of long message (formatted)';
    3.40 -       field bloblist attachments doc='blobs with attachements';
    3.41 -    field char rawmsg_ref doc='reference to raw message data';
    3.42 -    field size rawmsg_size doc='size of raw message data';
    3.43 +    field blob_list attachments doc='blobs with attachements';
    3.44 +    field blob_ref rawmsg_ref doc='reference to raw message data';
    3.45 +    field size_t rawmsg_size doc='size of raw message data';
    3.46      field timestamp sent doc='when the message is sent';
    3.47      field timestamp recv doc='when the message is received';
    3.48      field identity from doc='whom the message is from';
    3.49 @@ -47,20 +72,14 @@
    3.50      field identity_list cc doc='whom a CC is being sent';
    3.51      field identity_list bcc doc='whom a BCC is being sent';
    3.52      field identity_list reply_to doc='where a reply should go to';
    3.53 -    field string in_reply_to doc='list of strings with MessageIDs of refering messages';
    3.54 -    field struct _message refering_msg_ref doc='reference to refering message';
    3.55 -    field string references doc='list of strings with references';
    3.56 -    field struct _message_ref_list refered_by doc='list of references to messages being refered';
    3.57 -    field string keywords doc='list of strings with keywords';
    3.58 -    field string char comments doc='string with comments';
    3.59 +    field string_list in_reply_to doc='list of strings with MessageIDs of refering messages';
    3.60 +    field message_ref refering_msg_ref doc='reference to refering message';
    3.61 +    field string_list references doc='list of strings with references';
    3.62 +    field message_ref_list refered_by doc='list of references to messages being refered';
    3.63 +    field string_list keywords doc='list of strings with keywords';
    3.64 +    field string comments doc='string with comments';
    3.65      field stringpair_list opt_fields doc='optional fields';
    3.66 -    field enc_format enc_format doc='format of encrypted data';
    3.67 -}
    3.68 -
    3.69 -
    3.70 -struct message_ref_list {
    3.71 -    field message msg_ref doc='reference to message';
    3.72 -    field struct _message_ref_list next;
    3.73 +    field enc_format format doc='format of encrypted data';
    3.74  }
    3.75  
    3.76  
    3.77 @@ -119,9 +138,9 @@
    3.78          use message src doc="message to encrypt";
    3.79  
    3.80          create message dst
    3.81 -            doc="pointer to new encrypted message or NULL if no encryption could take place";
    3.82 +            doc="pointer to new encrypted message or empty if no encryption could take place";
    3.83  
    3.84 -        use const char to_fpr
    3.85 +        use hash to_fpr
    3.86              doc="fingerprint of the recipient key to which the private key should be encrypted";
    3.87  
    3.88          use enc_format format doc="encrypted format";
    3.89 @@ -168,7 +187,7 @@
    3.90  
    3.91          use hash_list extra doc="extra keys for encryption";
    3.92  
    3.93 -        create message dst doc="pointer to new encrypted message or NULL on failure";
    3.94 +        create message dst doc="pointer to new encrypted message or empty on failure";
    3.95  
    3.96          use enc_format format doc="encrypted format";
    3.97  
    3.98 @@ -184,7 +203,7 @@
    3.99              flag key_reset_only 0x20;
   3.100          }
   3.101  
   3.102 -        // exceptions doc="(FIXME: This may not be correct or complete)"
   3.103 +        doc | (FIXME: The exceptions may not be correct or complete)
   3.104  
   3.105          throws key_not_found doc="at least one of the receipient keys could not be found";
   3.106  
   3.107 @@ -197,53 +216,53 @@
   3.108      method decrypt_message
   3.109          doc="decrypt message in memory"
   3.110      {
   3.111 -    // parms
   3.112 +        // parms
   3.113  
   3.114 -    supply message src
   3.115 -    doc="""
   3.116 -        message to decrypt. 
   3.117 -        The ownership of src remains with the caller - however, the contents 
   3.118 -        might be modified (strings freed and allocated anew or set to NULL,
   3.119 -        etc) intentionally; when this happens, decrypt_flag_src_modified is set.
   3.120 -        """;
   3.121 +        supply message src
   3.122 +        doc="""
   3.123 +            message to decrypt. 
   3.124 +            The ownership of src remains with the caller - however, the contents 
   3.125 +            might be modified (strings freed and allocated anew or set to empty,
   3.126 +            etc) intentionally; when this happens, decrypt_flag_src_modified is set.
   3.127 +            """;
   3.128  
   3.129 -    create message dst doc="pointer to new decrypted message or NULL on failure";
   3.130 +        create message dst doc="pointer to new decrypted message or empty on failure";
   3.131  
   3.132 -    supply hash_list keylist
   3.133 -    doc="""
   3.134 -        in: stringlist with additional keyids for reencryption if needed
   3.135 -            (will be freed and replaced with output keylist)
   3.136 -        out: stringlist with keyids used for signing and encryption. first
   3.137 -            first key is signer, additional keys are the ones it was encrypted
   3.138 -            to. Only signer and whichever of the user's keys was used are reliable.
   3.139 -        The ownership of keylist goes to the caller.
   3.140 -        If src is unencrypted this function returns unencrypted and sets dst to NULL.
   3.141 -        """;
   3.142 +        supply hash_list keylist
   3.143 +        doc="""
   3.144 +            in: stringlist with additional keyids for reencryption if needed
   3.145 +                (will be freed and replaced with output keylist)
   3.146 +            out: stringlist with keyids used for signing and encryption. first
   3.147 +                first key is signer, additional keys are the ones it was encrypted
   3.148 +                to. Only signer and whichever of the user's keys was used are reliable.
   3.149 +            The ownership of keylist goes to the caller.
   3.150 +            If src is unencrypted this function returns unencrypted and sets dst to empty.
   3.151 +            """;
   3.152  
   3.153 -    return rating msg_rating doc="rating for the message";
   3.154 +        return rating msg_rating doc="rating for the message";
   3.155  
   3.156 -    // flags
   3.157 -    
   3.158 -    decrypt_flags {
   3.159 -        decrypt_flag_own_private_key 0x1 
   3.160 -        doc="""
   3.161 -            private key was imported for one of our addresses (NOT trusted
   3.162 -            or set to be used - handshake/trust is required for that)
   3.163 -            """;
   3.164 -        decrypt_flag_consume 0x2 doc=’used by sync';
   3.165 -        decrypt_flag_ignore 0x4 doc=’used by sync';
   3.166 -        decrypt_flag_src_modified 0x8 
   3.167 -        doc="""
   3.168 -            indicates that the src object has been modified. At the moment,
   3.169 -            this is always as a direct result of the behaviour driven
   3.170 -            by the input flags. This flag is the ONLY value that should be
   3.171 -            relied upon to see if such changes have taken place.
   3.172 -            """;
   3.173 -        decrypt_flag_untrusted_server 0x100 
   3.174 -        doc="""
   3.175 -            input flags. Used to signal that decrypt function should engage in behaviour
   3.176 -            specified for when the server storing the source is untrusted.
   3.177 -            """;
   3.178 +        // flags
   3.179 +        
   3.180 +        decrypt_flags {
   3.181 +            decrypt_flag_own_private_key 0x1 
   3.182 +            doc="""
   3.183 +                private key was imported for one of our addresses (NOT trusted
   3.184 +                or set to be used - handshake/trust is required for that)
   3.185 +                """;
   3.186 +            decrypt_flag_consume 0x2 doc=’used by sync';
   3.187 +            decrypt_flag_ignore 0x4 doc=’used by sync';
   3.188 +            decrypt_flag_src_modified 0x8 
   3.189 +            doc="""
   3.190 +                indicates that the src object has been modified. At the moment,
   3.191 +                this is always as a direct result of the behaviour driven
   3.192 +                by the input flags. This flag is the ONLY value that should be
   3.193 +                relied upon to see if such changes have taken place.
   3.194 +                """;
   3.195 +            decrypt_flag_untrusted_server 0x100 
   3.196 +            doc="""
   3.197 +                input flags. Used to signal that decrypt function should engage in behaviour
   3.198 +                specified for when the server storing the source is untrusted.
   3.199 +                """;
   3.200      }
   3.201  
   3.202      // exceptions
   3.203 @@ -259,10 +278,10 @@
   3.204      throws unencrypted
   3.205          doc="""
   3.206              if src is unencrypted this function returns unencrypted and sets
   3.207 -            dst to NULL.
   3.208 +            dst to empty.
   3.209              """;
   3.210  
   3.211 -    throws any doc="error status";
   3.212 +    throws any doc="all error status values allowed";
   3.213      }
   3.214  
   3.215  
   3.216 @@ -348,23 +367,21 @@
   3.217      {
   3.218      //parms
   3.219  
   3.220 -    use const identity id1 doc="identity of first party in communication - fpr can't be NULL";
   3.221 +    use identity id1 doc="identity of first party in communication - fpr can't be empty";
   3.222  
   3.223 -    use const identity id2 doc="identity of second party in communication - fpr can't be NULL";
   3.224 +    use identity id2 doc="identity of second party in communication - fpr can't be empty";
   3.225  
   3.226 -    use const char lang doc="C string with ISO 639-1 language code";
   3.227 +    use ISO639_1 lang doc="string with ISO 639-1 language code";
   3.228  
   3.229 -    create char words
   3.230 +    create string words
   3.231          doc="""
   3.232 -            pointer to C string with all trustwords UTF-8 encoded, separated 
   3.233 -            by a blank each NULL if language is not supported or trustword 
   3.234 +            string with all trustwords, separated 
   3.235 +            by a blank each. Empty if language is not supported or trustword 
   3.236              wordlist is damaged or unavailable. 
   3.237              The word pointer goes to the ownership of the caller. 
   3.238              The caller is responsible to free() it (on Windoze use pEp_free())
   3.239              """;
   3.240  
   3.241 -    create size_t wsize doc="length of full trustwords string";
   3.242 -
   3.243      use bool full
   3.244          doc="""
   3.245              if true, generate ALL trustwords for these identities.
   3.246 @@ -390,18 +407,16 @@
   3.247      use message msg doc="message to get sender identity from";
   3.248  
   3.249      use hash_list keylist
   3.250 -        doc="NULL if message to be decrypted, keylist returned by decrypt_message() otherwise.";
   3.251 +        doc="empty if message to be decrypted, keylist returned by decrypt_message() otherwise.";
   3.252  
   3.253 -    use identity received_by doc="identity for account receiving message can't be NULL";
   3.254 +    use identity received_by doc="identity for account receiving message can't be empty";
   3.255  
   3.256 -    use string lang doc="C string with ISO 639-1 language code";
   3.257 +    use ISO639_1 lang doc="C string with ISO 639-1 language code";
   3.258  
   3.259 -    create char words
   3.260 +    create string words
   3.261          doc="""
   3.262 -            pointer to C string with all trustwords UTF-8 encoded, separated by a blank each.
   3.263 -            NULL if language is not supported or trustword  wordlist is damaged or unavailable.
   3.264 -            The word pointer goes to the ownership of the caller. 
   3.265 -            The caller is responsible to free() it (on Windoze use pEp_free())
   3.266 +            string with all trustwords, separated by a blank each.
   3.267 +            Empty if language is not supported or trustword  wordlist is damaged or unavailable.
   3.268              """;
   3.269  
   3.270      use bool full
   3.271 @@ -441,7 +456,7 @@
   3.272          doc="""
   3.273              if decrypted message doesn't contain X-EncStatus optional field and 
   3.274              x_enc_status is pEp_rating_udefined or if decrypted message doesn't 
   3.275 -            contain X-Keylist optional field and x_keylist is NULL.
   3.276 +            contain X-Keylist optional field and x_keylist is empty.
   3.277              """;
   3.278  
   3.279      throws out_of_memory doc="if not enough memory could be allocated";
   3.280 @@ -467,50 +482,21 @@
   3.281  }    
   3.282  
   3.283  
   3.284 -    // ratings
   3.285 +func color_from_rating
   3.286 +    doc="calculate color from rating"
   3.287 +{
   3.288 +    // parms
   3.289  
   3.290 -    ratings {
   3.291 -        item rating_undefined 0;
   3.292 -        item rating_cannot_decrypt 1;
   3.293 -        item rating_have_no_key 2;
   3.294 -        item rating_unencrypted 3;
   3.295 -        item rating_unencrypted_for_some doc="don't use this any more",
   3.296 -        item rating_unreliable 4;
   3.297 -        item rating_reliable 5;
   3.298 -        item rating_trusted 6;
   3.299 -        item rating_trusted_and_anonymized 7;
   3.300 -        item rating_fully_anonymous 8;
   3.301 -        item rating_mistrust -1;
   3.302 -        item rating_b0rken -2;
   3.303 -        item rating_under_attack -3;
   3.304 -    }
   3.305 +    use color_from_rating rating doc="color representing that rating"
   3.306  
   3.307 -
   3.308 -    // colors
   3.309 -
   3.310 -    colors {
   3.311 -        item color_no_color 0;
   3.312 -        item color_yellow 1;
   3.313 -        item color_green 2;
   3.314 -        item color_red -1;
   3.315 -    }
   3.316 -
   3.317 -
   3.318 -    func color_from_rating
   3.319 -        doc="calculate color from rating"
   3.320 -    {
   3.321 -        // parms
   3.322 -
   3.323 -        use color_from_rating rating doc="color representing that rating"
   3.324 -
   3.325 -        // return value
   3.326 -        return color rating_color doc="color representing that rating"
   3.327 +    // return value
   3.328 +    return color rating_color doc="color representing that rating"
   3.329  }
   3.330  
   3.331 -            
   3.332 -    func get_binary_path
   3.333 -        doc="retrieve path of cryptotech binary if available"
   3.334 -    {
   3.335 +        
   3.336 +func get_binary_path
   3.337 +    doc="retrieve path of cryptotech binary if available"
   3.338 +{
   3.339      //parms
   3.340  
   3.341      use cryptotech tech
   3.342 @@ -518,7 +504,7 @@
   3.343  
   3.344      use string path
   3.345      doc="""
   3.346 -        path to cryptotech binary or NULL if not available. **path is owned by 
   3.347 +        path to cryptotech binary or empty if not available. **path is owned by 
   3.348          the library, do not change it!;
   3.349          """
   3.350  }
     4.1 --- a/api/pEp.yml2	Fri Feb 22 12:59:32 2019 +0100
     4.2 +++ b/api/pEp.yml2	Tue Mar 05 13:56:11 2019 +0100
     4.3 @@ -43,11 +43,23 @@
     4.4  // string:  text
     4.5  // int:     integer number
     4.6  // blob:    Binary Large Object
     4.7 +// size_t:  size in memory
     4.8 +// const:
     4.9 +// identity:
    4.10 +// message:
    4.11 +// rating:
    4.12 +// enc_format:
    4.13 +// hash:
    4.14 +// TID:
    4.15 +
    4.16  
    4.17  // collections
    4.18  
    4.19  // list:    one or more elements, which have a sequence
    4.20  // set:     one or more elements, which do not have a sequence
    4.21 +// pair:    two elements in sequence
    4.22 +
    4.23 +
    4.24  
    4.25  package pEp {
    4.26      api transport include ./transport_api.yml2
     5.1 --- a/src/message.h	Fri Feb 22 12:59:32 2019 +0100
     5.2 +++ b/src/message.h	Tue Mar 05 13:56:11 2019 +0100
     5.3 @@ -62,7 +62,7 @@
     5.4      stringlist_t *in_reply_to;              // list of UTF-8 strings with
     5.5                                              // MessageIDs of refering messages
     5.6      struct _message *refering_msg_ref;      // reference to refering message
     5.7 -    stringlist_t *references;               // list of UTF-8 strings with references
     5.8 +    stringlist_t * references;               // list of UTF-8 strings with references
     5.9      struct _message_ref_list *refered_by;   // list of references to messages being
    5.10                                              // refered
    5.11      stringlist_t *keywords;                 // list of UTF-8 strings with keywords