From 8587cc799f9cb45d1f18ff1256ce9aee72982e1a Mon Sep 17 00:00:00 2001
From: Poet (Tim Sally) <poet@stack.io>
Date: Tue, 16 Nov 2010 12:33:38 -0600
Subject: [PATCH 3/3] (1) Several updates to grammars for events and GETINFO results.  All relate
 to the fact that LongName has replaced ServerID since 0.2.2.1-alpha. See
 documentation of VERBOSE_NAMES for more information. The following
 grammars were changed:
   * orconn-status GETINFO result
   * entry-guards GETINFO result
   * Path general token
   * OR Connection status changed event
   * New descriptors available event
 In all cases a note was added about when the old grammar applies.

(2) Update to the description of entry-guards. The description incorrectly
said that the helper-nodes alias would be removed in 0.1.3.x. As of this
writing the helper-nodes alias is still in Tor.
---
 doc/spec/control-spec.txt |   58 +++++++++++++++++++++++++++++++-------------
 1 files changed, 41 insertions(+), 17 deletions(-)

diff --git a/doc/spec/control-spec.txt b/doc/spec/control-spec.txt
index 4a94e89..4e5c34b 100644
--- a/doc/spec/control-spec.txt
+++ b/doc/spec/control-spec.txt
@@ -481,27 +481,36 @@
          StreamID SP StreamStatus SP CircID SP Target CRLF
 
     "orconn-status"
-      A series of lines as for an OR connection status event.  Each is of the
-      form:
+      A series of lines as for an OR connection status event.  In Tor
+      0.1.2.2-alpha with feature VERBOSE_NAMES enabled and in Tor
+      0.2.2.1-alpha and later by default, each line is of the form:
+         LongName SP ORStatus CRLF
+
+     Before 0.1.2.2-alpha, each line is of the form:
          ServerID SP ORStatus CRLF
 
     "entry-guards"
       A series of lines listing the currently chosen entry guards, if any.
-      Each is of the form:
+      In Tor 0.1.2.2-alpha with feature VERBOSE_NAMES enabled and in Tor
+      0.2.2.1-alpha and later by default, each line is of the form:
+         LongName SP Status [SP ISOTime] CRLF
+
+      Before 0.1.2.2-alpha, each line is of the form:
          ServerID2 SP Status [SP ISOTime] CRLF
+         ServerID2 = Nickname / 40*HEXDIG
 
-         Status-with-time = ("unlisted") SP ISOTime
-         Status = ("up" / "never-connected" / "down" /
-                      "unusable" / "unlisted" )
+      The definition of Status is the same for both:
+         Status = "up" / "never-connected" / "down" /
+                  "unusable" / "unlisted"
 
-         ServerID2 = Nickname / 40*HEXDIG
 
-      [From 0.1.1.4-alpha to 0.1.1.10-alpha, this was called "helper-nodes".
-       Tor still supports calling it that for now, but support will be
-       removed in 0.1.3.x.]
 
-      [Older versions of Tor (before 0.1.2.x-final) generated 'down' instead
-       of unlisted/unusable.  Current Tors never generate 'down'.]
+      From 0.1.1.4-alpha to 0.1.1.10-alpha, entry-guards was called
+      "helper-nodes". Tor still supports calling "helper-nodes", but it
+      is depricated and should not be used
+
+      [Note that older versions of Tor (before 0.1.2.x-final) generated 'down'
+      instead of unlisted/unusable.  Current Tors never generate 'down'.]
 
       [XXXX ServerID2 differs from ServerID in not prefixing fingerprints
        with a $.  This is an implementation error.  It would be nice to add
@@ -1005,7 +1014,11 @@
                "FAILED"   / ; circuit closed (was not built)
                "CLOSED"     ; circuit closed (was built)
 
-      Path = ServerID *("," ServerID)
+      Path = LongName *("," LongName)
+        ; In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature
+        ; VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, Path
+        ; is as follows:
+        Path = ServerID *("," ServerID)
 
       Reason = "NONE" / "TORPROTOCOL" / "INTERNAL" / "REQUESTED" /
                "HIBERNATING" / "RESOURCELIMIT" / "CONNECTFAILED" /
@@ -1094,19 +1107,26 @@
 4.1.3. OR Connection status changed
 
   The syntax is:
-    "650" SP "ORCONN" SP (ServerID / Target) SP ORStatus [ SP "REASON="
+
+    "650" SP "ORCONN" SP (LongName / Target) SP ORStatus [ SP "REASON="
              Reason ] [ SP "NCIRCS=" NumCircuits ] CRLF
 
     ORStatus = "NEW" / "LAUNCHED" / "CONNECTED" / "FAILED" / "CLOSED"
 
+        ; In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature
+        ; VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, OR
+        ; Connection is as follows:
+        "650" SP "ORCONN" SP (ServerID / Target) SP ORStatus [ SP "REASON="
+                 Reason ] [ SP "NCIRCS=" NumCircuits ] CRLF
+
   NEW is for incoming connections, and LAUNCHED is for outgoing
   connections. CONNECTED means the TLS handshake has finished (in
   either direction). FAILED means a connection is being closed that
   hasn't finished its handshake, and CLOSED is for connections that
   have handshaked.
 
-  A ServerID is specified unless it's a NEW connection, in which
-  case we don't know what server it is yet, so we use Address:Port.
+  A LongName or ServerID is specified unless it's a NEW connection, in
+  which case we don't know what server it is yet, so we use Address:Port.
 
   If extended events are enabled (see 3.19), optional reason and
   circuit counting information is provided for CLOSED and FAILED
@@ -1143,7 +1163,11 @@
 4.1.6. New descriptors available
 
   Syntax:
-     "650" SP "NEWDESC" 1*(SP ServerID) CRLF
+     "650" SP "NEWDESC" 1*(SP LongName) CRLF
+        ; In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature
+        ; VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, it
+        ; is as follows:
+        "650" SP "NEWDESC" 1*(SP ServerID) CRLF
 
 4.1.7. New Address mapping
 
-- 
1.7.3.1

