pEpObjCAdapter/PEPSession.h
author Dirk Zimmermann <dirk@pep-project.org>
Wed, 17 May 2017 09:27:57 +0200
changeset 187 1f630a05e444
child 196 d660aae03056
permissions -rw-r--r--
IOSAD-15 more renames
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
dirk@187
    43
/** Encrypt a message */
dirk@187
    44
- (PEP_STATUS)encryptMessageDict:(nonnull NSDictionary<NSString *, id> *)src
dirk@187
    45
                           extra:(nullable NSArray<NSString *> *)keys
dirk@187
    46
                            dest:(NSDictionary<NSString *, id> * _Nullable * _Nullable)dst;
dirk@187
    47
dirk@187
    48
/** Encrypt a message for the given identity, which is usually a mySelf identity */
dirk@187
    49
- (PEP_STATUS)encryptMessageDict:(nonnull NSDictionary<NSString *, id> *)src
dirk@187
    50
                        identity:(nonnull NSDictionary<NSString *, id> *)identity
dirk@187
    51
                            dest:(NSDictionary<NSString *, id> * _Nullable * _Nullable)dst;
dirk@187
    52
dirk@187
    53
/** Determine the status color of a message to be sent */
dirk@187
    54
- (PEP_rating)outgoingMessageColor:(nonnull NSDictionary<NSString *, id> *)msg;
dirk@187
    55
dirk@187
    56
/** Determine the rating of an identity */
dirk@187
    57
- (PEP_rating)identityRating:(nonnull NSDictionary<NSString *, id> *)identity;
dirk@187
    58
dirk@187
    59
/** Get trustwords for a fingerprint */
dirk@187
    60
- (nonnull NSArray *)trustwords:(nonnull NSString *)fpr forLanguage:(nonnull NSString *)languageID
dirk@187
    61
                      shortened:(BOOL)shortened;
dirk@187
    62
dirk@187
    63
/**
dirk@187
    64
 Supply an account used by our user himself. The identity is supplemented with the missing parts
dirk@187
    65
dirk@187
    66
 An identity is a `NSDictionary` mapping a field name as `NSString` to different values.
dirk@187
    67
 An identity can have the following fields (all other keys are ignored).
dirk@187
    68
 It is not necessary to supply all fields; missing fields are supplemented by p≡p engine.
dirk@187
    69
 
dirk@187
    70
 @"username": real name or nick name (if pseudonymous) of identity
dirk@187
    71
 @"address": URI or SMTP address
dirk@187
    72
 @"user_id": persistent unique ID for identity
dirk@187
    73
 @"lang": preferred languageID for communication with this ID (default: @"en")
dirk@187
    74
 @"fpr": fingerprint of key to use for communication with this ID
dirk@187
    75
 @"comm_type": communication type code (usually not needed)
dirk@187
    76
 @"me": YES if this is an identity of our user, NO if it is one of a communication partner (default: NO)
dirk@187
    77
 
dirk@187
    78
 As an example:
dirk@187
    79
 
dirk@187
    80
 User has a mailbox. The mail address is "Dipul Khatri <dipul@inboxcube.com>". Then this would be:
dirk@187
    81
 
dirk@187
    82
 NSDictionary *ident = [NSDictionary dictionaryWithObjectsAndKeys:
dirk@187
    83
 @"Dipul Khatri", @"username", @"dipul@inboxcube.com", @"address", 
dirk@187
    84
 @"23", @"user_id", nil];
dirk@187
    85
 
dirk@187
    86
*/
dirk@187
    87
- (void)mySelf:(nonnull NSMutableDictionary<NSString *, id> *)identity;
dirk@187
    88
dirk@187
    89
/**
dirk@187
    90
 Supplement missing information for an arbitrary identity (used for communication partners).
dirk@187
    91
 See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
dirk@187
    92
 */
dirk@187
    93
- (void)updateIdentity:(nonnull NSMutableDictionary<NSString *, id> *)identity;
dirk@187
    94
dirk@187
    95
/**
dirk@187
    96
 Mark a key as trusted with a person.
dirk@187
    97
 See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
dirk@187
    98
 */
dirk@187
    99
- (void)trustPersonalKey:(nonnull NSMutableDictionary<NSString *, id> *)identity;
dirk@187
   100
dirk@187
   101
/**
dirk@187
   102
 if a key is not trusted by the user tell this using this message
dirk@187
   103
 See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
dirk@187
   104
 */
dirk@187
   105
- (void)keyMistrusted:(nonnull NSMutableDictionary<NSString *, id> *)identity;
dirk@187
   106
dirk@187
   107
/**
dirk@187
   108
 Use this to undo keyCompromized or trustPersonalKey
dirk@187
   109
 See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
dirk@187
   110
*/
dirk@187
   111
- (void)keyResetTrust:(nonnull NSMutableDictionary<NSString *, id> *)identity;
dirk@187
   112
dirk@187
   113
#pragma mark -- Internal API (testing etc.)
dirk@187
   114
dirk@187
   115
/** For testing purpose, manual key import */
dirk@187
   116
- (void)importKey:(nonnull NSString *)keydata;
dirk@187
   117
dirk@187
   118
- (void)logTitle:(nonnull NSString *)title entity:(nonnull NSString *)entity
dirk@187
   119
     description:(nullable NSString *)description comment:(nullable NSString *)comment;
dirk@187
   120
dirk@187
   121
/**
dirk@187
   122
 Retrieves the log from the engine.
dirk@187
   123
 */
dirk@187
   124
- (nonnull NSString *)getLog;
dirk@187
   125
dirk@187
   126
/** Determine trustwords for two identities */
dirk@187
   127
- (nullable NSString *)getTrustwordsIdentity1:(nonnull NSDictionary<NSString *, id> *)identity1
dirk@187
   128
                                    identity2:(nonnull NSDictionary<NSString *, id> *)identity2
dirk@187
   129
                                     language:(nullable NSString *)language
dirk@187
   130
                                         full:(BOOL)full;
dirk@187
   131
dirk@187
   132
/**
dirk@187
   133
 @returns The list of supported languages for trustwords.
dirk@187
   134
 */
dirk@187
   135
- (NSArray<PEPLanguage *> * _Nonnull)languageList;
dirk@187
   136
dirk@187
   137
@end