pEpObjCAdapter/PEPSession.h
author buff <andreas@pep-project.org>
Fri, 20 Oct 2017 12:47:55 +0200
branchIOSAD-50
changeset 290 19e6db3d1767
parent 287 640d621c9dbf
child 293 4a4ae2aaf760
permissions -rw-r--r--
IOSAD-50 we take over the responsibility for creating and holding a session for the main thread
     1 //
     2 //  PEPSession.h
     3 //  pEpObjCAdapter
     4 //
     5 //  Created by Andreas Buff on 11.10.17.
     6 //  Copyright © 2017 p≡p. All rights reserved.
     7 //
     8 
     9 #import <Foundation/Foundation.h>
    10 
    11 #import "PEPMessage.h"
    12 
    13 typedef NSDictionary<NSString *, id> PEPDict;
    14 typedef NSMutableDictionary<NSString *, id> PEPMutableDict;
    15 typedef NSArray<NSString *> PEPStringList;
    16 
    17 @class PEPLanguage;
    18 
    19 /**
    20  Fake session to handle to the client.
    21 
    22  Assures all calls are handled on the correct internal session for the thread it is called on.
    23  You can instatntiate and use this session how often and wherever you want. Also over multiple threads.
    24 
    25  Note: You must call `cleanup()` once before your process gets terminated to be able to gracefully shutdown.
    26  It is the clients responsibility not to make any calls to PEPSession in between the last call
    27  // to `cleanup()` and getting terminated.
    28  */
    29 @interface PEPSession : NSObject
    30 
    31 /**
    32  You must call this method once before your process gets terminated to be able to gracefully shutdown.
    33  You must not make any calls to PEPSession in between the last call to `cleanup()` and getting terminated.
    34 
    35  Only for performance reasons: call this method only if you have to.
    36  */
    37 - (void)cleanup;
    38 
    39 /** Decrypt a message */
    40 - (PEP_rating)decryptMessageDict:(nonnull PEPDict *)src
    41                             dest:(PEPDict * _Nullable * _Nullable)dst
    42                             keys:(PEPStringList * _Nullable * _Nullable)keys;
    43 
    44 /** Re-evaluate rating of decrypted message */
    45 - (PEP_rating)reEvaluateMessageRating:(nonnull PEPDict *)src;
    46 
    47 /** Encrypt a message */
    48 - (PEP_STATUS)encryptMessageDict:(nonnull PEPDict *)src
    49                            extra:(nullable PEPStringList *)keys
    50                             dest:(PEPDict * _Nullable * _Nullable)dst;
    51 
    52 /** Encrypt a message for the given identity, which is usually a mySelf identity */
    53 - (PEP_STATUS)encryptMessageDict:(nonnull PEPDict *)src
    54                         identity:(nonnull PEPDict *)identity
    55                             dest:(PEPDict * _Nullable * _Nullable)dst;
    56 
    57 /** Determine the status color of a message to be sent */
    58 - (PEP_rating)outgoingMessageColor:(nonnull PEPDict *)msg;
    59 
    60 /** Determine the rating of an identity */
    61 - (PEP_rating)identityRating:(nonnull PEPDict *)identity;
    62 
    63 /** Get trustwords for a fingerprint */
    64 - (nonnull NSArray *)trustwords:(nonnull NSString *)fpr forLanguage:(nonnull NSString *)languageID
    65                       shortened:(BOOL)shortened;
    66 
    67 /**
    68  Supply an account used by our user himself. The identity is supplemented with the missing parts
    69 
    70  An identity is a `NSDictionary` mapping a field name as `NSString` to different values.
    71  An identity can have the following fields (all other keys are ignored).
    72  It is not necessary to supply all fields; missing fields are supplemented by p≡p engine.
    73 
    74  @"username": real name or nick name (if pseudonymous) of identity
    75  @"address": URI or SMTP address
    76  @"user_id": persistent unique ID for identity
    77  @"lang": preferred languageID for communication with this ID (default: @"en")
    78  @"fpr": fingerprint of key to use for communication with this ID
    79  @"comm_type": communication type code (usually not needed)
    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 PEPMutableDict *)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 PEPMutableDict *)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 PEPMutableDict *)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 PEPMutableDict *)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 PEPMutableDict *)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 PEPDict *)identity1
   131                                     identity2:(nonnull PEPDict *)identity2
   132                                      language:(nullable NSString *)language
   133                                          full:(BOOL)full;
   134 
   135 /** Determine trustwords between sender of a message and receiving identity */
   136 - (nullable NSString *)getTrustwordsMessageDict:(nonnull PEPDict *)messageDict
   137                                    receiverDict:(nonnull PEPDict *)receiverDict
   138                                       keysArray:(PEPStringList * _Nullable)keysArray
   139                                        language:(nullable NSString *)language
   140                                            full:(BOOL)full
   141                                 resultingStatus:(PEP_STATUS * _Nullable)resultingStatus;
   142 
   143 /**
   144  @returns The list of supported languages for trustwords.
   145  */
   146 - (NSArray<PEPLanguage *> * _Nonnull)languageList;
   147 
   148 /**
   149  Directly invokes the engine's undo_last_mistrust() function
   150  */
   151 - (PEP_STATUS)undoLastMistrust;
   152 
   153 @end