version 2: ist edits from nana generate_api
authornk
Fri, 15 Feb 2019 15:16:43 +0100
branchgenerate_api
changeset 32989b65e15820d5
parent 3297 21c1c1b8b51f
child 3302 9bcfd8ff14a9
version 2: ist edits from nana
api/message_api.yml2
     1.1 --- a/api/message_api.yml2	Thu Feb 14 18:34:23 2019 +0100
     1.2 +++ b/api/message_api.yml2	Fri Feb 15 15:16:43 2019 +0100
     1.3 @@ -28,7 +28,7 @@
     1.4              take place
     1.5              """
     1.6  
     1.7 -        use encformat format doc="encrypted format";
     1.8 +        use enc_format enc_format doc="encrypted format";
     1.9  
    1.10          // flags
    1.11  
    1.12 @@ -53,26 +53,22 @@
    1.13              and key is attached to it 
    1.14              """
    1.15      }
    1.16 -}
    1.17  
    1.18  
    1.19 -protocol session {
    1.20  	method encrypt_message_and_add_priv_key
    1.21  		doc="encrypt message in memory, adding an encrypted private key (encrypted separately and sent within the inner message)"
    1.22  	{
    1.23  		// parms
    1.24  
    1.25 -		use message src 
    1.26 -		doc="message to encrypt";
    1.27 +		use message src doc="message to encrypt";
    1.28  
    1.29  		create message dst
    1.30  		doc="pointer to new encrypted message or NULL if no encryption could take place";
    1.31  
    1.32 -		to_fpr
    1.33 +		const char to_fpr
    1.34  		doc="fingerprint of the recipient key to which the private key should be encrypted";
    1.35  
    1.36 -		use format enc_format?
    1.37 -		doc="encrypted format";
    1.38 +		use enc_format enc_format doc="encrypted format";
    1.39  
    1.40  		// flags
    1.41  
    1.42 @@ -97,10 +93,8 @@
    1.43  				and key is attached to it
    1.44  				"""
    1.45  	}
    1.46 -}
    1.47  
    1.48  
    1.49 -protocol session {
    1.50  	method encrypt_message_for_self
    1.51  		doc="""
    1.52  			encrypt message in memory for user's identity only,
    1.53 @@ -109,20 +103,19 @@
    1.54  	{
    1.55  		// parms
    1.56  
    1.57 -		use message target_id
    1.58 -		doc="self identity this message should be encrypted for";
    1.59 +		use identity target_id
    1.60 +		doc="""
    1.61 +			self identity this message should be encrypted for. message is NOT encrypted for 
    1.62 +			identities other than the target_id (and then, only if the target_id refers to self!)
    1.63 +			""";
    1.64  
    1.65 -		use message src
    1.66 -		doc="message to encrypt";
    1.67 +		use message src doc="message to encrypt";
    1.68  
    1.69 -		provide key? extra
    1.70 -		doc="extra keys for encryption";
    1.71 +		provide hash_list extra doc="extra keys for encryption";
    1.72  
    1.73 -		create message dst
    1.74 -		doc="pointer to new encrypted message or NULL on failure";
    1.75 +		create message dst doc="pointer to new encrypted message or NULL on failure";
    1.76  
    1.77 -		use format enc_format?
    1.78 -		doc="encrypted format";
    1.79 +		use enc_format enc_format? doc="encrypted format";
    1.80  
    1.81  		// flags
    1.82  
    1.83 @@ -147,16 +140,14 @@
    1.84  		throws get_key_failed
    1.85  			doc="cannot retrieve key"
    1.86  	}
    1.87 -}
    1.88  
    1.89  
    1.90 -protocol session {
    1.91  	method color_from_rating
    1.92  		doc="calculate color from rating"
    1.93  	{
    1.94  		// parms
    1.95  	
    1.96 -		provide message rating?
    1.97 +		provide color_from_rating rating
    1.98  		doc="color representing that rating";
    1.99  
   1.100  		// ratings
   1.101 @@ -189,10 +180,8 @@
   1.102  		// return value
   1.103  			doc="color representing that rating"
   1.104  	}
   1.105 -}
   1.106  
   1.107  
   1.108 -protocol session {
   1.109  	method decrypt_message
   1.110  		doc="decrypt message in memory"
   1.111  	{
   1.112 @@ -209,7 +198,7 @@
   1.113  	create message dst
   1.114  	doc="pointer to new decrypted message or NULL on failure";
   1.115  
   1.116 -	supply message keylist
   1.117 +	supply hash_list keylist
   1.118  	doc="""
   1.119  		in: stringlist with additional keyids for reencryption if needed
   1.120  			(will be freed and replaced with output keylist)
   1.121 @@ -218,7 +207,7 @@
   1.122  			to. Only signer and whichever of the user's keys was used are reliable.
   1.123  		""";
   1.124  
   1.125 -	return message rating
   1.126 +	return rating rating
   1.127  	doc="rating for the message";
   1.128  
   1.129  	// flags
   1.130 @@ -262,10 +251,8 @@
   1.131  			dst to NULL.
   1.132  			"""
   1.133  	}
   1.134 -}
   1.135  
   1.136  
   1.137 -protocol session {
   1.138  	method own_message_private_key_details
   1.139  		doc="details on own key in own message"
   1.140  	{
   1.141 @@ -277,13 +264,11 @@
   1.142  		can check own signature.
   1.143  		""";
   1.144  
   1.145 -	create @type? ident
   1.146 +	create identity ident
   1.147  	doc="identity containing uid, address and fpr of key"
   1.148  	}
   1.149 -}
   1.150  
   1.151  
   1.152 -protocol session {
   1.153  	method outgoing_message_rating
   1.154  		doc="get rating for an outgoing message"
   1.155  	{
   1.156 @@ -295,13 +280,11 @@
   1.157  		Dir must be dir_outgoing.
   1.158  		""";
   1.159  
   1.160 -	create message rating
   1.161 +	create rating rating
   1.162  	doc="rating for the message"
   1.163  	}
   1.164 -}
   1.165  
   1.166  
   1.167 -protocol session {
   1.168  	method outgoing_message_rating_preview
   1.169  		doc="get rating preview"
   1.170  	{
   1.171 @@ -313,28 +296,24 @@
   1.172  		Dir must be dir_outgoing.
   1.173  		""";
   1.174  
   1.175 -	create message rating
   1.176 +	create rating rating
   1.177  	doc="rating preview for the message"
   1.178  	}
   1.179 -}
   1.180  
   1.181  
   1.182 -protocol session {
   1.183  	method identity_rating
   1.184  		doc="get rating for a single identity"
   1.185  	{
   1.186  	//parms
   1.187  
   1.188 -	use @type ident
   1.189 +	use identity ident
   1.190  	doc="identity to get the rating for";
   1.191  
   1.192 -	create identity rating
   1.193 +	create rating rating
   1.194  	doc="rating for the identity"
   1.195  	}
   1.196 -}
   1.197  
   1.198  
   1.199 -protocol session {
   1.200  	method get_binary_path
   1.201  		doc="retrieve path of cryptotech binary if available"
   1.202  	{
   1.203 @@ -349,25 +328,23 @@
   1.204  		the library, do not change it!
   1.205  		"""
   1.206  	}
   1.207 -}
   1.208  
   1.209  
   1.210 -protocol session {
   1.211  	method get_trustwords
   1.212  		doc="get full trustwords string for a *pair* of identities"
   1.213  	{
   1.214  	//parms
   1.215  
   1.216 -	provide message id1
   1.217 +	provide const identity id1
   1.218  		doc="identity of first party in communication - fpr can't be NULL";
   1.219  
   1.220 -	provide message id2
   1.221 +	provide const identity id2
   1.222  		doc="identity of second party in communication - fpr can't be NULL";
   1.223  
   1.224 -	provide message lang
   1.225 +	provide const char lang
   1.226  		doc="C string with ISO 639-1 language code";
   1.227  
   1.228 -	create message words
   1.229 +	create char words
   1.230  		doc="""
   1.231  			pointer to C string with all trustwords UTF-8 encoded, separated 
   1.232  			by a blank each NULL if language is not supported or trustword 
   1.233 @@ -376,10 +353,10 @@
   1.234  			The caller is responsible to free() it (on Windoze use pEp_free())
   1.235  			""";
   1.236  
   1.237 -	create @type? wsize
   1.238 +	create size_t wsize
   1.239  		doc="length of full trustwords string";
   1.240  
   1.241 -	provide @type full
   1.242 +	provide bool full
   1.243  		doc="""
   1.244  			if true, generate ALL trustwords for these identities.
   1.245  			else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
   1.246 @@ -394,28 +371,26 @@
   1.247  	throws trustword_not_found
   1.248  		doc="at least one trustword not found"
   1.249  	}
   1.250 -}
   1.251  
   1.252  
   1.253 -protocol session
   1.254  	method get_message_trustwords
   1.255  		doc="get full trustwords string for message sender and reciever identities"
   1.256  	{
   1.257  	//parms
   1.258  
   1.259 -	provide @type msg
   1.260 +	provide message msg
   1.261  		doc="message to get sender identity from";
   1.262  
   1.263 -	provide message keylist
   1.264 +	provide hash_list keylist
   1.265  		doc="NULL if message to be decrypted, keylist returned by decrypt_message() otherwise.";
   1.266  
   1.267 -	provide message received_by
   1.268 +	provide identity received_by
   1.269  		doc="identity for account receiving message can't be NULL";
   1.270  
   1.271 -	provide @type? lang
   1.272 +	provide const char lang
   1.273  		doc="C string with ISO 639-1 language code";
   1.274  
   1.275 -	create message words
   1.276 +	create char words
   1.277  		doc="""
   1.278  			pointer to C string with all trustwords UTF-8 encoded, separated by a blank each.
   1.279  			NULL if language is not supported or trustword  wordlist is damaged or unavailable.
   1.280 @@ -423,7 +398,7 @@
   1.281  			The caller is responsible to free() it (on Windoze use pEp_free())
   1.282  			""";
   1.283  
   1.284 -	provide @type full
   1.285 +	provide bool full
   1.286  		doc="""
   1.287  			if true, generate ALL trustwords for these identities.
   1.288  			else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
   1.289 @@ -438,22 +413,20 @@
   1.290  	throws trustword_not_found
   1.291  		doc="at least one trustword not found"
   1.292  	}
   1.293 -}
   1.294  
   1.295  
   1.296 -protocol session
   1.297  	method re_evaluate_message_rating
   1.298  		doc="re-evaluate already decrypted message rating"
   1.299  	{
   1.300  	//parms
   1.301  
   1.302 -	use @type msg
   1.303 +	use message msg
   1.304  		doc="message to get the rating for. msg->from must point to a valid pEp_identity";
   1.305  
   1.306 -	use message x_keylist
   1.307 +	use hash_list x_keylist
   1.308  		doc="decrypted message recipients keys fpr";
   1.309  
   1.310 -	provide message x_enc_status
   1.311 +	provide rating x_enc_status
   1.312  		doc="original rating for the decrypted message";
   1.313  
   1.314  	create message rating
   1.315 @@ -471,22 +444,20 @@
   1.316  	throws out_of_memory
   1.317  		doc="if not enough memory could be allocated"
   1.318  	}
   1.319 -}
   1.320  
   1.321  
   1.322 -protocol session
   1.323  	method get_key_rating_for_user
   1.324  		doc="get the rating of a certain key for a certain user"
   1.325  	{
   1.326  	//parms
   1.327  
   1.328 -	provide @type? user_id
   1.329 +	provide const char user_id
   1.330  		doc="string with user ID";
   1.331  
   1.332 -	provide @type fpr
   1.333 +	provide const char fpr
   1.334  		doc="string with fingerprint";
   1.335  
   1.336 -	create @type rating
   1.337 +	create rating rating
   1.338  		doc="rating of key for this user"
   1.339  		
   1.340  	// exceptions