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