merge IOSAD-114
authorDirk Zimmermann <dz@pep.security>
Fri, 02 Aug 2019 08:16:26 +0200
changeset 113506aa7abea2b3
parent 1098 7e325f306580
parent 1134 f41e4690c6f7
child 1136 09715c6d4ecf
child 1148 c4f93603e74d
merge IOSAD-114
     1.1 --- a/pEpObjCAdapterFramework/PEPNotifyHandshakeDelegate.h	Wed Jul 24 10:04:00 2019 +0200
     1.2 +++ b/pEpObjCAdapterFramework/PEPNotifyHandshakeDelegate.h	Fri Aug 02 08:16:26 2019 +0200
     1.3 @@ -12,8 +12,29 @@
     1.4  
     1.5  @class PEPIdentity;
     1.6  
     1.7 +/**
     1.8 + Handles notifications from the engine to the app that involve UI.
     1.9 + */
    1.10  @protocol PEPNotifyHandshakeDelegate <NSObject>
    1.11  
    1.12 +/**
    1.13 + Requests the app to show a handshake dialog, or change the icon that represents
    1.14 + the key-sync state (as in, grouped, or sole, etc.).
    1.15 +
    1.16 + After the dialog has been shown, the user's choices can be communicated back to the engine
    1.17 + via [PEPSessionProtocol deliverHandshakeResult:identitiesSharing:error].
    1.18 +
    1.19 + @param object This can be used to thread information from the app through the sync-loop back to
    1.20 +               the app. Currently unused and always nil.
    1.21 + @param me The own identity.
    1.22 +           Note that in some cases, only the most essential properties are set.
    1.23 + @param partner The partner identity.
    1.24 +                Note that in some cases, only the most essential properties are set.
    1.25 + @param signal The kind of action that is happening or requested.
    1.26 + @return A status indicating errors in the immediate/synchronous handling of the call.
    1.27 +         The (delayed) response from the user are communicated to the engine
    1.28 +         via separate method calls, as noted in the discussion.
    1.29 + */
    1.30  - (PEPStatus)notifyHandshake:(void * _Nullable)object
    1.31                            me:(PEPIdentity * _Nonnull)me
    1.32                       partner:(PEPIdentity * _Nonnull)partner
     2.1 --- a/pEpObjCAdapterFramework/PEPSendMessageDelegate.h	Wed Jul 24 10:04:00 2019 +0200
     2.2 +++ b/pEpObjCAdapterFramework/PEPSendMessageDelegate.h	Fri Aug 02 08:16:26 2019 +0200
     2.3 @@ -12,8 +12,20 @@
     2.4  
     2.5  @class PEPMessage;
     2.6  
     2.7 +/**
     2.8 + Delegate that receives notifications when the engine needs to send out messages on its behalf.
     2.9 + */
    2.10  @protocol PEPSendMessageDelegate <NSObject>
    2.11  
    2.12 +/**
    2.13 + Called when the engine wants to send out a message, which is generally invisible to the user.
    2.14 +
    2.15 + @param message The message to be sent out.
    2.16 + @return A status value that can indicate failure if it's already obvious at call-time (sync)
    2.17 +         that there is something wrong with the message. Can only cover immediate problems.
    2.18 +         Issues that can occur while sending the message (later) cannot (and should not)
    2.19 +         be communicated back to the engine. The app should simply retry.
    2.20 + */
    2.21  - (PEPStatus)sendMessage:(PEPMessage * _Nonnull)message;
    2.22  
    2.23  @end
     3.1 --- a/pEpObjCAdapterFramework/PEPSessionProtocol.h	Wed Jul 24 10:04:00 2019 +0200
     3.2 +++ b/pEpObjCAdapterFramework/PEPSessionProtocol.h	Fri Aug 02 08:16:26 2019 +0200
     3.3 @@ -253,7 +253,18 @@
     3.4             error:(NSError * _Nullable * _Nullable)error;
     3.5  
     3.6  /**
     3.7 - Wraps the engine's deliverHandshakeResult.
     3.8 + Indicate the user's choice during a handshake dialog display.
     3.9 +
    3.10 + Wraps the engine's deliverHandshakeResult. Should be called in response to
    3.11 + [PEPNotifyHandshakeDelegate notifyHandshake:me:partner:signal
    3.12 + in accordance with the user's choices.
    3.13 +
    3.14 + @param result The choice the user made with regards to the currently active handshake dialog.
    3.15 + @param identitiesSharing The identities that are involved for the user's choice.
    3.16 +                          That is, the user can chose to respond only for a subset of the
    3.17 +                          identities that were originally involved in the handshake.
    3.18 + @param error The default cocoa error handling.
    3.19 + @return `YES` when the call succedded, `NO` otherwise. In the `NO` case, see `error` for details.
    3.20   */
    3.21  - (BOOL)deliverHandshakeResult:(PEPSyncHandshakeResult)result
    3.22               identitiesSharing:(NSArray<PEPIdentity *> * _Nullable)identitiesSharing
     4.1 --- a/pEpObjCAdapterFramework/PEPSync.h	Wed Jul 24 10:04:00 2019 +0200
     4.2 +++ b/pEpObjCAdapterFramework/PEPSync.h	Fri Aug 02 08:16:26 2019 +0200
     4.3 @@ -14,21 +14,38 @@
     4.4  @class PEPSyncSendMessageDelegate;
     4.5  
     4.6  /**
     4.7 - @see libpEpAdapter: Adapter.{cc|hh}
     4.8 - @see sync_codec.h
     4.9 + Manages the key-sync loop.
    4.10   */
    4.11  @interface PEPSync : NSObject
    4.12  
    4.13  @property (nonatomic, nullable, weak) id<PEPSendMessageDelegate> sendMessageDelegate;
    4.14  @property (nonatomic, nullable, weak) id<PEPNotifyHandshakeDelegate> notifyHandshakeDelegate;
    4.15  
    4.16 +/**
    4.17 + Manages the key-sync loop, and other key-sync related elements.
    4.18 +
    4.19 + @note This object should only exist once per app.
    4.20 +
    4.21 + @param sendMessageDelegate Will be called on behalf of the engine for outgoing messages,
    4.22 +                            needed e.g. in case of key rest, or for key-sync.
    4.23 + @param notifyHandshakeDelegate Called whever there is a key-sync related information that
    4.24 +                                should be displayed to the user.
    4.25 + @return The object that binds the delegates given in the constructor and can be used to control
    4.26 +         the key-sync loop.
    4.27 + */
    4.28  - (instancetype _Nonnull)initWithSendMessageDelegate:(id <PEPSendMessageDelegate>
    4.29                                                        _Nullable)sendMessageDelegate
    4.30                               notifyHandshakeDelegate:(id<PEPNotifyHandshakeDelegate>
    4.31                                                        _Nullable)notifyHandshakeDelegate;
    4.32  
    4.33 +/**
    4.34 + Start the key-sync loop in its own, separate thread.
    4.35 + */
    4.36  - (void)startup;
    4.37  
    4.38 +/**
    4.39 + Shuts the key-sync loop down.
    4.40 + */
    4.41  - (void)shutdown;
    4.42  
    4.43  @end