version 2: ist edits from nana

api/message_api.yml2

@@ -28,7 +28,7 @@ protocol session {
             take place
             """
 
-        use encformat format doc="encrypted format";
+        use enc_format enc_format doc="encrypted format";
 
         // flags
 
@@ -53,26 +53,22 @@ protocol session {
             and key is attached to it 
             """
     }
-}
 
 
-protocol session {
 	method encrypt_message_and_add_priv_key
 		doc="encrypt message in memory, adding an encrypted private key (encrypted separately and sent within the inner message)"
 	{
 		// parms
 
-		use message src 
-		doc="message to encrypt";
+		use message src doc="message to encrypt";
 
 		create message dst
 		doc="pointer to new encrypted message or NULL if no encryption could take place";
 
-		to_fpr
+		const char to_fpr
 		doc="fingerprint of the recipient key to which the private key should be encrypted";
 
-		use format enc_format?
-		doc="encrypted format";
+		use enc_format enc_format doc="encrypted format";
 
 		// flags
 
@@ -97,10 +93,8 @@ protocol session {
 				and key is attached to it
 				"""
 	}
-}
 
 
-protocol session {
 	method encrypt_message_for_self
 		doc="""
 			encrypt message in memory for user's identity only,
@@ -109,20 +103,19 @@ protocol session {
 	{
 		// parms
 
-		use message target_id
-		doc="self identity this message should be encrypted for";
+		use identity target_id
+		doc="""
+			self identity this message should be encrypted for. message is NOT encrypted for 
+			identities other than the target_id (and then, only if the target_id refers to self!)
+			""";
 
-		use message src
-		doc="message to encrypt";
+		use message src doc="message to encrypt";
 
-		provide key? extra
-		doc="extra keys for encryption";
+		provide hash_list extra doc="extra keys for encryption";
 
-		create message dst
-		doc="pointer to new encrypted message or NULL on failure";
+		create message dst doc="pointer to new encrypted message or NULL on failure";
 
-		use format enc_format?
-		doc="encrypted format";
+		use enc_format enc_format? doc="encrypted format";
 
 		// flags
 
@@ -147,16 +140,14 @@ protocol session {
 		throws get_key_failed
 			doc="cannot retrieve key"
 	}
-}
 
 
-protocol session {
 	method color_from_rating
 		doc="calculate color from rating"
 	{
 		// parms
 	
-		provide message rating?
+		provide color_from_rating rating
 		doc="color representing that rating";
 
 		// ratings
@@ -189,10 +180,8 @@ protocol session {
 		// return value
 			doc="color representing that rating"
 	}
-}
 
 
-protocol session {
 	method decrypt_message
 		doc="decrypt message in memory"
 	{
@@ -209,7 +198,7 @@ protocol session {
 	create message dst
 	doc="pointer to new decrypted message or NULL on failure";
 
-	supply message keylist
+	supply hash_list keylist
 	doc="""
 		in: stringlist with additional keyids for reencryption if needed
 			(will be freed and replaced with output keylist)
@@ -218,7 +207,7 @@ protocol session {
 			to. Only signer and whichever of the user's keys was used are reliable.
 		""";
 
-	return message rating
+	return rating rating
 	doc="rating for the message";
 
 	// flags
@@ -262,10 +251,8 @@ protocol session {
 			dst to NULL.
 			"""
 	}
-}
 
 
-protocol session {
 	method own_message_private_key_details
 		doc="details on own key in own message"
 	{
@@ -277,13 +264,11 @@ protocol session {
 		can check own signature.
 		""";
 
-	create @type? ident
+	create identity ident
 	doc="identity containing uid, address and fpr of key"
 	}
-}
 
 
-protocol session {
 	method outgoing_message_rating
 		doc="get rating for an outgoing message"
 	{
@@ -295,13 +280,11 @@ protocol session {
 		Dir must be dir_outgoing.
 		""";
 
-	create message rating
+	create rating rating
 	doc="rating for the message"
 	}
-}
 
 
-protocol session {
 	method outgoing_message_rating_preview
 		doc="get rating preview"
 	{
@@ -313,28 +296,24 @@ protocol session {
 		Dir must be dir_outgoing.
 		""";
 
-	create message rating
+	create rating rating
 	doc="rating preview for the message"
 	}
-}
 
 
-protocol session {
 	method identity_rating
 		doc="get rating for a single identity"
 	{
 	//parms
 
-	use @type ident
+	use identity ident
 	doc="identity to get the rating for";
 
-	create identity rating
+	create rating rating
 	doc="rating for the identity"
 	}
-}
 
 
-protocol session {
 	method get_binary_path
 		doc="retrieve path of cryptotech binary if available"
 	{
@@ -349,25 +328,23 @@ protocol session {
 		the library, do not change it!
 		"""
 	}
-}
 
 
-protocol session {
 	method get_trustwords
 		doc="get full trustwords string for a *pair* of identities"
 	{
 	//parms
 
-	provide message id1
+	provide const identity id1
 		doc="identity of first party in communication - fpr can't be NULL";
 
-	provide message id2
+	provide const identity id2
 		doc="identity of second party in communication - fpr can't be NULL";
 
-	provide message lang
+	provide const char lang
 		doc="C string with ISO 639-1 language code";
 
-	create message words
+	create char words
 		doc="""
 			pointer to C string with all trustwords UTF-8 encoded, separated 
 			by a blank each NULL if language is not supported or trustword 
@@ -376,10 +353,10 @@ protocol session {
 			The caller is responsible to free() it (on Windoze use pEp_free())
 			""";
 
-	create @type? wsize
+	create size_t wsize
 		doc="length of full trustwords string";
 
-	provide @type full
+	provide bool full
 		doc="""
 			if true, generate ALL trustwords for these identities.
 			else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
@@ -394,28 +371,26 @@ protocol session {
 	throws trustword_not_found
 		doc="at least one trustword not found"
 	}
-}
 
 
-protocol session
 	method get_message_trustwords
 		doc="get full trustwords string for message sender and reciever identities"
 	{
 	//parms
 
-	provide @type msg
+	provide message msg
 		doc="message to get sender identity from";
 
-	provide message keylist
+	provide hash_list keylist
 		doc="NULL if message to be decrypted, keylist returned by decrypt_message() otherwise.";
 
-	provide message received_by
+	provide identity received_by
 		doc="identity for account receiving message can't be NULL";
 
-	provide @type? lang
+	provide const char lang
 		doc="C string with ISO 639-1 language code";
 
-	create message words
+	create char words
 		doc="""
 			pointer to C string with all trustwords UTF-8 encoded, separated by a blank each.
 			NULL if language is not supported or trustword  wordlist is damaged or unavailable.
@@ -423,7 +398,7 @@ protocol session
 			The caller is responsible to free() it (on Windoze use pEp_free())
 			""";
 
-	provide @type full
+	provide bool full
 		doc="""
 			if true, generate ALL trustwords for these identities.
 			else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
@@ -438,22 +413,20 @@ protocol session
 	throws trustword_not_found
 		doc="at least one trustword not found"
 	}
-}
 
 
-protocol session
 	method re_evaluate_message_rating
 		doc="re-evaluate already decrypted message rating"
 	{
 	//parms
 
-	use @type msg
+	use message msg
 		doc="message to get the rating for. msg->from must point to a valid pEp_identity";
 
-	use message x_keylist
+	use hash_list x_keylist
 		doc="decrypted message recipients keys fpr";
 
-	provide message x_enc_status
+	provide rating x_enc_status
 		doc="original rating for the decrypted message";
 
 	create message rating
@@ -471,22 +444,20 @@ protocol session
 	throws out_of_memory
 		doc="if not enough memory could be allocated"
 	}
-}
 
 
-protocol session
 	method get_key_rating_for_user
 		doc="get the rating of a certain key for a certain user"
 	{
 	//parms
 
-	provide @type? user_id
+	provide const char user_id
 		doc="string with user ID";
 
-	provide @type fpr
+	provide const char fpr
 		doc="string with fingerprint";
 
-	create @type rating
+	create rating rating
 		doc="rating of key for this user"
 		
 	// exceptions