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