1 files changed, 79 insertions, 1 deletions

diff --git a/src/Network/Tox/NodeId.hs b/src/Network/Tox/NodeId.hs
index 3a732b43..d5da692a 100644
--- a/src/Network/Tox/NodeId.hs
+++ b/src/Network/Tox/NodeId.hs
@@ -33,7 +33,10 @@ module Network.Tox.NodeId
     , parseNoSpamId
     , nospam64
     , nospam16
-    , verifyChecksum) where
+    , verifyChecksum
+    , ToxContact(..)
+    , ToxProgress(..)
+    ) where
 
 import Control.Applicative
 import Control.Arrow
@@ -617,3 +620,78 @@ solveBase64NoSpamID b64digits pub = do
     let nospam' = fromIntegral (n64' `shiftR` 32)
         cksum'  = fromIntegral (n64' `shiftR` 16)
     return $ NoSpamId (NoSpam nospam' (Just cksum')) pub
+
+-- | This type indicates a roster-link relationship between a local toxid and a
+-- remote toxid.  Note that these toxids are represented as the type 'NodeId'
+-- even though they are long-term keys rather than the public keys of Tox DHT
+-- nodes.
+data ToxContact = ToxContact NodeId{-me-} NodeId{-them-}
+ deriving (Eq,Ord)
+
+instance Show ToxContact where show = show . showToxContact_
+
+showToxContact_ :: ToxContact -> String
+showToxContact_ (ToxContact me them) = show me ++ ":" ++ show them
+
+-- | This type indicates the progress of a tox encrypted friend link
+-- connection.  Two scenarios are illustrated below.  The parenthesis show the
+-- current 'G.Status' 'ToxProgress' of the session.
+--
+--
+-- Perfect handshake scenario:
+--
+--  Peer 1                                  Peer 2
+--  (InProgress AcquiringCookie)            (Dormant/InProgress AcquiringCookie)
+--                     Cookie request ->
+--                                       <- Cookie response
+--  (InProgress AwaitingHandshake)          (Dormant/InProgress AcquiringCookie)
+--                   Handshake packet ->
+--                                          * accepts connection
+--                                          (InProgress AwaitingSessionPacket)
+--                                       <- Handshake packet
+--  *accepts connection
+--  (InProgress AwaitingSessionPacket)
+--                   Encrypted packet -> <- Encrypted packet
+--  *confirms connection                    *confirms connection
+--  (Established)                           (Established)
+--
+--                           Connection successful.
+--
+--                  Encrypted packets -> <- Encrypted packets
+--
+--
+--
+--
+--  More realistic handshake scenario:
+--  Peer 1                                  Peer 2
+--  (InProgress AcquiringCookie)            (Dormant/InProgress AcquiringCookie)
+--                      Cookie request ->   *packet lost*
+--                      Cookie request ->
+--                                        <- Cookie response
+--  (InProgress AwaitingHandshake)           (Dormant/InProgress AcquiringCookie)
+--
+--                                           *Peer 2 randomly starts new connection to peer 1
+--                                           (InProgress AcquiringCookie)
+--                                        <- Cookie request
+--                     Cookie response ->
+--                                           (InProgress AwaitingHandshake)
+--
+--                    Handshake packet -> <- Handshake packet
+--  *accepts connection                      * accepts connection
+--  (InProgress AwaitingSessionPacket)      (InProgress AwaitingSessionPacket)
+--
+--                    Encrypted packet -> <- Encrypted packet
+--  *confirms connection                     *confirms connection
+--  (Established)                           (Established)
+--
+--                              Connection successful.
+--
+--                   Encrypted packets -> <- Encrypted packets
+data ToxProgress
+    = AwaitingDHTKey        -- ^ Waiting to receive their DHT key.
+    | AcquiringIPAddress    -- ^ Searching DHT to obtain their node's IP & port.
+    | AcquiringCookie       -- ^ Attempting to obtain a cookie.
+    | AwaitingHandshake     -- ^ Waiting to receive a handshake.
+    | AwaitingSessionPacket -- ^ Connection is "accepted" but not yet "confirmed".
+    deriving (Eq,Ord,Enum,Show)
+