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