pEpObjCAdapter/PEPSession.h
changeset 187 1f630a05e444
child 196 d660aae03056
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/pEpObjCAdapter/PEPSession.h	Wed May 17 09:27:57 2017 +0200
     1.3 @@ -0,0 +1,137 @@
     1.4 +//
     1.5 +//  PEPSession.h
     1.6 +//  pEpiOSAdapter
     1.7 +//
     1.8 +//  Created by Volker Birk on 08.07.15.
     1.9 +//  Copyright (c) 2015 p≡p. All rights reserved.
    1.10 +//
    1.11 +
    1.12 +#import <Foundation/Foundation.h>
    1.13 +
    1.14 +#import "PEPObjCAdapter.h"
    1.15 +#import "PEPMessage.h"
    1.16 +
    1.17 +@class PEPSession;
    1.18 +@class PEPLanguage;
    1.19 +
    1.20 +/** Callback type for doing something with a session */
    1.21 +typedef void (^PEPSessionBlock)(PEPSession * _Nonnull session);
    1.22 +
    1.23 +@interface PEPSession : NSObject
    1.24 +
    1.25 +#pragma mark -- Public API
    1.26 +
    1.27 ++ (nonnull PEPSession *)session;
    1.28 +
    1.29 +/**
    1.30 + Execute a block concurrently on a session.
    1.31 + The session is created solely for execution of the block.
    1.32 + */
    1.33 ++ (void)dispatchAsyncOnSession:(nonnull PEPSessionBlock)block;
    1.34 +
    1.35 +/**
    1.36 + Execute a block on a session and wait for it.
    1.37 + The session is created solely for execution of the block.
    1.38 + */
    1.39 ++ (void)dispatchSyncOnSession:(nonnull PEPSessionBlock)block;
    1.40 +
    1.41 +/** Decrypt a message */
    1.42 +- (PEP_rating)decryptMessageDict:(nonnull NSDictionary<NSString *, id> *)src
    1.43 +                            dest:(NSDictionary<NSString *, id> * _Nullable * _Nullable)dst
    1.44 +                            keys:(NSArray<NSString *> * _Nullable * _Nullable)keys;
    1.45 +
    1.46 +/** Encrypt a message */
    1.47 +- (PEP_STATUS)encryptMessageDict:(nonnull NSDictionary<NSString *, id> *)src
    1.48 +                           extra:(nullable NSArray<NSString *> *)keys
    1.49 +                            dest:(NSDictionary<NSString *, id> * _Nullable * _Nullable)dst;
    1.50 +
    1.51 +/** Encrypt a message for the given identity, which is usually a mySelf identity */
    1.52 +- (PEP_STATUS)encryptMessageDict:(nonnull NSDictionary<NSString *, id> *)src
    1.53 +                        identity:(nonnull NSDictionary<NSString *, id> *)identity
    1.54 +                            dest:(NSDictionary<NSString *, id> * _Nullable * _Nullable)dst;
    1.55 +
    1.56 +/** Determine the status color of a message to be sent */
    1.57 +- (PEP_rating)outgoingMessageColor:(nonnull NSDictionary<NSString *, id> *)msg;
    1.58 +
    1.59 +/** Determine the rating of an identity */
    1.60 +- (PEP_rating)identityRating:(nonnull NSDictionary<NSString *, id> *)identity;
    1.61 +
    1.62 +/** Get trustwords for a fingerprint */
    1.63 +- (nonnull NSArray *)trustwords:(nonnull NSString *)fpr forLanguage:(nonnull NSString *)languageID
    1.64 +                      shortened:(BOOL)shortened;
    1.65 +
    1.66 +/**
    1.67 + Supply an account used by our user himself. The identity is supplemented with the missing parts
    1.68 +
    1.69 + An identity is a `NSDictionary` mapping a field name as `NSString` to different values.
    1.70 + An identity can have the following fields (all other keys are ignored).
    1.71 + It is not necessary to supply all fields; missing fields are supplemented by p≡p engine.
    1.72 + 
    1.73 + @"username": real name or nick name (if pseudonymous) of identity
    1.74 + @"address": URI or SMTP address
    1.75 + @"user_id": persistent unique ID for identity
    1.76 + @"lang": preferred languageID for communication with this ID (default: @"en")
    1.77 + @"fpr": fingerprint of key to use for communication with this ID
    1.78 + @"comm_type": communication type code (usually not needed)
    1.79 + @"me": YES if this is an identity of our user, NO if it is one of a communication partner (default: NO)
    1.80 + 
    1.81 + As an example:
    1.82 + 
    1.83 + User has a mailbox. The mail address is "Dipul Khatri <dipul@inboxcube.com>". Then this would be:
    1.84 + 
    1.85 + NSDictionary *ident = [NSDictionary dictionaryWithObjectsAndKeys:
    1.86 + @"Dipul Khatri", @"username", @"dipul@inboxcube.com", @"address", 
    1.87 + @"23", @"user_id", nil];
    1.88 + 
    1.89 +*/
    1.90 +- (void)mySelf:(nonnull NSMutableDictionary<NSString *, id> *)identity;
    1.91 +
    1.92 +/**
    1.93 + Supplement missing information for an arbitrary identity (used for communication partners).
    1.94 + See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
    1.95 + */
    1.96 +- (void)updateIdentity:(nonnull NSMutableDictionary<NSString *, id> *)identity;
    1.97 +
    1.98 +/**
    1.99 + Mark a key as trusted with a person.
   1.100 + See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
   1.101 + */
   1.102 +- (void)trustPersonalKey:(nonnull NSMutableDictionary<NSString *, id> *)identity;
   1.103 +
   1.104 +/**
   1.105 + if a key is not trusted by the user tell this using this message
   1.106 + See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
   1.107 + */
   1.108 +- (void)keyMistrusted:(nonnull NSMutableDictionary<NSString *, id> *)identity;
   1.109 +
   1.110 +/**
   1.111 + Use this to undo keyCompromized or trustPersonalKey
   1.112 + See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
   1.113 +*/
   1.114 +- (void)keyResetTrust:(nonnull NSMutableDictionary<NSString *, id> *)identity;
   1.115 +
   1.116 +#pragma mark -- Internal API (testing etc.)
   1.117 +
   1.118 +/** For testing purpose, manual key import */
   1.119 +- (void)importKey:(nonnull NSString *)keydata;
   1.120 +
   1.121 +- (void)logTitle:(nonnull NSString *)title entity:(nonnull NSString *)entity
   1.122 +     description:(nullable NSString *)description comment:(nullable NSString *)comment;
   1.123 +
   1.124 +/**
   1.125 + Retrieves the log from the engine.
   1.126 + */
   1.127 +- (nonnull NSString *)getLog;
   1.128 +
   1.129 +/** Determine trustwords for two identities */
   1.130 +- (nullable NSString *)getTrustwordsIdentity1:(nonnull NSDictionary<NSString *, id> *)identity1
   1.131 +                                    identity2:(nonnull NSDictionary<NSString *, id> *)identity2
   1.132 +                                     language:(nullable NSString *)language
   1.133 +                                         full:(BOOL)full;
   1.134 +
   1.135 +/**
   1.136 + @returns The list of supported languages for trustwords.
   1.137 + */
   1.138 +- (NSArray<PEPLanguage *> * _Nonnull)languageList;
   1.139 +
   1.140 +@end