pEpObjCAdapter/PEPSession.h
author buff <andreas@pep-project.org>
Tue, 10 Oct 2017 12:25:29 +0200
branchIOSAD-50
changeset 264 32f2cfb49568
parent 255 e8749386fdf0
child 268 afba0883d4d9
permissions -rw-r--r--
IOSAD-50 removes dead code
     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 typedef NSDictionary<NSString *, id> PEPDict;
    15 typedef NSMutableDictionary<NSString *, id> PEPMutableDict;
    16 typedef NSArray<NSString *> PEPStringList;
    17 
    18 @class PEPSession;
    19 @class PEPLanguage;
    20 
    21 /**
    22  N threads <-> N sessions, with the constraint that a session is never used
    23  in a pEpEngine call more than once at the same time.
    24  */
    25 @interface PEPSession : NSObject
    26 
    27 /** Decrypt a message */
    28 - (PEP_rating)decryptMessageDict:(nonnull PEPDict *)src
    29                             dest:(PEPDict * _Nullable * _Nullable)dst
    30                             keys:(PEPStringList * _Nullable * _Nullable)keys;
    31 
    32 /** Re-evaluate rating of decrypted message */
    33 - (PEP_rating)reEvaluateMessageRating:(nonnull PEPDict *)src;
    34 
    35 /** Encrypt a message */
    36 - (PEP_STATUS)encryptMessageDict:(nonnull PEPDict *)src
    37                            extra:(nullable PEPStringList *)keys
    38                             dest:(PEPDict * _Nullable * _Nullable)dst;
    39 
    40 /** Encrypt a message for the given identity, which is usually a mySelf identity */
    41 - (PEP_STATUS)encryptMessageDict:(nonnull PEPDict *)src
    42                         identity:(nonnull PEPDict *)identity
    43                             dest:(PEPDict * _Nullable * _Nullable)dst;
    44 
    45 /** Determine the status color of a message to be sent */
    46 - (PEP_rating)outgoingMessageColor:(nonnull PEPDict *)msg;
    47 
    48 /** Determine the rating of an identity */
    49 - (PEP_rating)identityRating:(nonnull PEPDict *)identity;
    50 
    51 /** Get trustwords for a fingerprint */
    52 - (nonnull NSArray *)trustwords:(nonnull NSString *)fpr forLanguage:(nonnull NSString *)languageID
    53                       shortened:(BOOL)shortened;
    54 
    55 /**
    56  Supply an account used by our user himself. The identity is supplemented with the missing parts
    57 
    58  An identity is a `NSDictionary` mapping a field name as `NSString` to different values.
    59  An identity can have the following fields (all other keys are ignored).
    60  It is not necessary to supply all fields; missing fields are supplemented by p≡p engine.
    61 
    62  @"username": real name or nick name (if pseudonymous) of identity
    63  @"address": URI or SMTP address
    64  @"user_id": persistent unique ID for identity
    65  @"lang": preferred languageID for communication with this ID (default: @"en")
    66  @"fpr": fingerprint of key to use for communication with this ID
    67  @"comm_type": communication type code (usually not needed)
    68 
    69  As an example:
    70 
    71  User has a mailbox. The mail address is "Dipul Khatri <dipul@inboxcube.com>". Then this would be:
    72 
    73  NSDictionary *ident = [NSDictionary dictionaryWithObjectsAndKeys:
    74  @"Dipul Khatri", @"username", @"dipul@inboxcube.com", @"address",
    75  @"23", @"user_id", nil];
    76 
    77  */
    78 - (void)mySelf:(nonnull PEPMutableDict *)identity;
    79 
    80 /**
    81  Supplement missing information for an arbitrary identity (used for communication partners).
    82  See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
    83  */
    84 - (void)updateIdentity:(nonnull PEPMutableDict *)identity;
    85 
    86 /**
    87  Mark a key as trusted with a person.
    88  See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
    89  */
    90 - (void)trustPersonalKey:(nonnull PEPMutableDict *)identity;
    91 
    92 /**
    93  if a key is not trusted by the user tell this using this message
    94  See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
    95  */
    96 - (void)keyMistrusted:(nonnull PEPMutableDict *)identity;
    97 
    98 /**
    99  Use this to undo keyCompromized or trustPersonalKey
   100  See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
   101  */
   102 - (void)keyResetTrust:(nonnull PEPMutableDict *)identity;
   103 
   104 #pragma mark -- Internal API (testing etc.)
   105 
   106 /** For testing purpose, manual key import */
   107 - (void)importKey:(nonnull NSString *)keydata;
   108 
   109 - (void)logTitle:(nonnull NSString *)title entity:(nonnull NSString *)entity
   110      description:(nullable NSString *)description comment:(nullable NSString *)comment;
   111 
   112 /**
   113  Retrieves the log from the engine.
   114  */
   115 - (nonnull NSString *)getLog;
   116 
   117 /** Determine trustwords for two identities */
   118 - (nullable NSString *)getTrustwordsIdentity1:(nonnull PEPDict *)identity1
   119                                     identity2:(nonnull PEPDict *)identity2
   120                                      language:(nullable NSString *)language
   121                                          full:(BOOL)full;
   122 
   123 /** Determine trustwords between sender of a message and receiving identity */
   124 - (nullable NSString *)getTrustwordsMessageDict:(nonnull PEPDict *)messageDict
   125                                    receiverDict:(nonnull PEPDict *)receiverDict
   126                                       keysArray:(PEPStringList * _Nullable)keysArray
   127                                        language:(nullable NSString *)language
   128                                            full:(BOOL)full
   129                                 resultingStatus:(PEP_STATUS * _Nullable)resultingStatus;
   130 
   131 /**
   132  @returns The list of supported languages for trustwords.
   133  */
   134 - (NSArray<PEPLanguage *> * _Nonnull)languageList;
   135 
   136 /**
   137  Directly invokes the engine's undo_last_mistrust() function
   138  */
   139 - (PEP_STATUS)undoLastMistrust;
   140 
   141 @end