pEpObjCAdapter/PEPSession.h
author Edouard Tisserant <edouard@pep-project.org>
Tue, 06 Jun 2017 15:32:01 +0200
changeset 196 d660aae03056
parent 187 1f630a05e444
child 198 55e448e712a6
permissions -rw-r--r--
ENGINE-179 added reEvaluateMessageRating, calling engine's re_evaluate_message_rating
     1 //
     2 //  PEPSession.h
     3 //  pEpiOSAdapter
     4 //
     5 //  Created by Volker Birk on 08.07.15.
     6 //  Copyright (c) 2015 p≡p. All rights reserved.
     7 //
     8 
     9 #import <Foundation/Foundation.h>
    10 
    11 #import "PEPObjCAdapter.h"
    12 #import "PEPMessage.h"
    13 
    14 @class PEPSession;
    15 @class PEPLanguage;
    16 
    17 /** Callback type for doing something with a session */
    18 typedef void (^PEPSessionBlock)(PEPSession * _Nonnull session);
    19 
    20 @interface PEPSession : NSObject
    21 
    22 #pragma mark -- Public API
    23 
    24 + (nonnull PEPSession *)session;
    25 
    26 /**
    27  Execute a block concurrently on a session.
    28  The session is created solely for execution of the block.
    29  */
    30 + (void)dispatchAsyncOnSession:(nonnull PEPSessionBlock)block;
    31 
    32 /**
    33  Execute a block on a session and wait for it.
    34  The session is created solely for execution of the block.
    35  */
    36 + (void)dispatchSyncOnSession:(nonnull PEPSessionBlock)block;
    37 
    38 /** Decrypt a message */
    39 - (PEP_rating)decryptMessageDict:(nonnull NSDictionary<NSString *, id> *)src
    40                             dest:(NSDictionary<NSString *, id> * _Nullable * _Nullable)dst
    41                             keys:(NSArray<NSString *> * _Nullable * _Nullable)keys;
    42 
    43 /** Re-evaluate rating of decrypted message */
    44 - (PEP_rating)reEvaluateMessageRating:(nonnull NSDictionary<NSString *, id> *)src;
    45 
    46 /** Encrypt a message */
    47 - (PEP_STATUS)encryptMessageDict:(nonnull NSDictionary<NSString *, id> *)src
    48                            extra:(nullable NSArray<NSString *> *)keys
    49                             dest:(NSDictionary<NSString *, id> * _Nullable * _Nullable)dst;
    50 
    51 /** Encrypt a message for the given identity, which is usually a mySelf identity */
    52 - (PEP_STATUS)encryptMessageDict:(nonnull NSDictionary<NSString *, id> *)src
    53                         identity:(nonnull NSDictionary<NSString *, id> *)identity
    54                             dest:(NSDictionary<NSString *, id> * _Nullable * _Nullable)dst;
    55 
    56 /** Determine the status color of a message to be sent */
    57 - (PEP_rating)outgoingMessageColor:(nonnull NSDictionary<NSString *, id> *)msg;
    58 
    59 /** Determine the rating of an identity */
    60 - (PEP_rating)identityRating:(nonnull NSDictionary<NSString *, id> *)identity;
    61 
    62 /** Get trustwords for a fingerprint */
    63 - (nonnull NSArray *)trustwords:(nonnull NSString *)fpr forLanguage:(nonnull NSString *)languageID
    64                       shortened:(BOOL)shortened;
    65 
    66 /**
    67  Supply an account used by our user himself. The identity is supplemented with the missing parts
    68 
    69  An identity is a `NSDictionary` mapping a field name as `NSString` to different values.
    70  An identity can have the following fields (all other keys are ignored).
    71  It is not necessary to supply all fields; missing fields are supplemented by p≡p engine.
    72  
    73  @"username": real name or nick name (if pseudonymous) of identity
    74  @"address": URI or SMTP address
    75  @"user_id": persistent unique ID for identity
    76  @"lang": preferred languageID for communication with this ID (default: @"en")
    77  @"fpr": fingerprint of key to use for communication with this ID
    78  @"comm_type": communication type code (usually not needed)
    79  @"me": YES if this is an identity of our user, NO if it is one of a communication partner (default: NO)
    80  
    81  As an example:
    82  
    83  User has a mailbox. The mail address is "Dipul Khatri <dipul@inboxcube.com>". Then this would be:
    84  
    85  NSDictionary *ident = [NSDictionary dictionaryWithObjectsAndKeys:
    86  @"Dipul Khatri", @"username", @"dipul@inboxcube.com", @"address", 
    87  @"23", @"user_id", nil];
    88  
    89 */
    90 - (void)mySelf:(nonnull NSMutableDictionary<NSString *, id> *)identity;
    91 
    92 /**
    93  Supplement missing information for an arbitrary identity (used for communication partners).
    94  See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
    95  */
    96 - (void)updateIdentity:(nonnull NSMutableDictionary<NSString *, id> *)identity;
    97 
    98 /**
    99  Mark a key as trusted with a person.
   100  See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
   101  */
   102 - (void)trustPersonalKey:(nonnull NSMutableDictionary<NSString *, id> *)identity;
   103 
   104 /**
   105  if a key is not trusted by the user tell this using this message
   106  See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
   107  */
   108 - (void)keyMistrusted:(nonnull NSMutableDictionary<NSString *, id> *)identity;
   109 
   110 /**
   111  Use this to undo keyCompromized or trustPersonalKey
   112  See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
   113 */
   114 - (void)keyResetTrust:(nonnull NSMutableDictionary<NSString *, id> *)identity;
   115 
   116 #pragma mark -- Internal API (testing etc.)
   117 
   118 /** For testing purpose, manual key import */
   119 - (void)importKey:(nonnull NSString *)keydata;
   120 
   121 - (void)logTitle:(nonnull NSString *)title entity:(nonnull NSString *)entity
   122      description:(nullable NSString *)description comment:(nullable NSString *)comment;
   123 
   124 /**
   125  Retrieves the log from the engine.
   126  */
   127 - (nonnull NSString *)getLog;
   128 
   129 /** Determine trustwords for two identities */
   130 - (nullable NSString *)getTrustwordsIdentity1:(nonnull NSDictionary<NSString *, id> *)identity1
   131                                     identity2:(nonnull NSDictionary<NSString *, id> *)identity2
   132                                      language:(nullable NSString *)language
   133                                          full:(BOOL)full;
   134 
   135 /**
   136  @returns The list of supported languages for trustwords.
   137  */
   138 - (NSArray<PEPLanguage *> * _Nonnull)languageList;
   139 
   140 @end