pEpObjCAdapter/PEPSession.h
author Dirk Zimmermann <dirk@pep-project.org>
Thu, 31 Aug 2017 11:55:57 +0200
changeset 202 9887f3326221
parent 198 55e448e712a6
child 205 41629fe43cc9
permissions -rw-r--r--
IOSAD-25 getTrustwordsMessageDict (untested, but compiles)
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
 
dirk@187
    80
 As an example:
dirk@187
    81
 
dirk@187
    82
 User has a mailbox. The mail address is "Dipul Khatri <dipul@inboxcube.com>". Then this would be:
dirk@187
    83
 
dirk@187
    84
 NSDictionary *ident = [NSDictionary dictionaryWithObjectsAndKeys:
dirk@187
    85
 @"Dipul Khatri", @"username", @"dipul@inboxcube.com", @"address", 
dirk@187
    86
 @"23", @"user_id", nil];
dirk@187
    87
 
dirk@187
    88
*/
dirk@187
    89
- (void)mySelf:(nonnull NSMutableDictionary<NSString *, id> *)identity;
dirk@187
    90
dirk@187
    91
/**
dirk@187
    92
 Supplement missing information for an arbitrary identity (used for communication partners).
dirk@187
    93
 See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
dirk@187
    94
 */
dirk@187
    95
- (void)updateIdentity:(nonnull NSMutableDictionary<NSString *, id> *)identity;
dirk@187
    96
dirk@187
    97
/**
dirk@187
    98
 Mark a key as trusted with a person.
dirk@187
    99
 See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
dirk@187
   100
 */
dirk@187
   101
- (void)trustPersonalKey:(nonnull NSMutableDictionary<NSString *, id> *)identity;
dirk@187
   102
dirk@187
   103
/**
dirk@187
   104
 if a key is not trusted by the user tell this using this message
dirk@187
   105
 See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
dirk@187
   106
 */
dirk@187
   107
- (void)keyMistrusted:(nonnull NSMutableDictionary<NSString *, id> *)identity;
dirk@187
   108
dirk@187
   109
/**
dirk@187
   110
 Use this to undo keyCompromized or trustPersonalKey
dirk@187
   111
 See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
dirk@187
   112
*/
dirk@187
   113
- (void)keyResetTrust:(nonnull NSMutableDictionary<NSString *, id> *)identity;
dirk@187
   114
dirk@187
   115
#pragma mark -- Internal API (testing etc.)
dirk@187
   116
dirk@187
   117
/** For testing purpose, manual key import */
dirk@187
   118
- (void)importKey:(nonnull NSString *)keydata;
dirk@187
   119
dirk@187
   120
- (void)logTitle:(nonnull NSString *)title entity:(nonnull NSString *)entity
dirk@187
   121
     description:(nullable NSString *)description comment:(nullable NSString *)comment;
dirk@187
   122
dirk@187
   123
/**
dirk@187
   124
 Retrieves the log from the engine.
dirk@187
   125
 */
dirk@187
   126
- (nonnull NSString *)getLog;
dirk@187
   127
dirk@187
   128
/** Determine trustwords for two identities */
dirk@187
   129
- (nullable NSString *)getTrustwordsIdentity1:(nonnull NSDictionary<NSString *, id> *)identity1
dirk@187
   130
                                    identity2:(nonnull NSDictionary<NSString *, id> *)identity2
dirk@187
   131
                                     language:(nullable NSString *)language
dirk@187
   132
                                         full:(BOOL)full;
dirk@187
   133
dirk@202
   134
/** Determine trustwords between sender of a message and receiving identity */
dirk@202
   135
- (nullable NSString *)getTrustwordsMessageDict:(nonnull NSDictionary<NSString *, id> *)messageDict
dirk@202
   136
                                   receiverDict:(nonnull NSDictionary<NSString *, id> *)receiverDict
dirk@202
   137
                                      keysArray:(NSArray<NSString *> * _Nullable)keysArray
dirk@202
   138
                                       language:(nullable NSString *)language
dirk@202
   139
                                           full:(BOOL)full;
dirk@202
   140
dirk@187
   141
/**
dirk@187
   142
 @returns The list of supported languages for trustwords.
dirk@187
   143
 */
dirk@187
   144
- (NSArray<PEPLanguage *> * _Nonnull)languageList;
dirk@187
   145
dirk@187
   146
@end