Updated Debug spec.

Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>

1 files changed, 97 insertions, 43 deletions

diff --git a/extensions/Debug.xml b/extensions/Debug.xml
index 96c4cfb7d..a21d9db60 100644
--- a/extensions/Debug.xml
+++ b/extensions/Debug.xml
@@ -17,96 +17,150 @@ Lesser General Public License for more details.</p>
 License along with this library; if not, write to the Free Software
 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
   </tp:license>
-  <interface name="org.freedesktop.Telepathy.Debug">
+  <interface name="org.freedesktop.Telepathy.Debug.DRAFT"
+    tp:causes-havoc="experimental">
+    <tp:added version="0.17.24"/>
 
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-      <p>An interface for providing debug messages.
+      <p>An interface for providing debug messages.</p>
 
-         This interface is primarily provided by one object per
-         service, at the path <tt>/org/freedesktop/Telepathy/debug</tt>.
-      </p>
+      <p>This interface is primarily provided by one object per
+      service, at the path <tt>/org/freedesktop/Telepathy/debug</tt>.</p>
     </tp:docstring>
 
-    <property name="Enabled" type="b" access="readwrite">
-      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>TRUE if the NewDebugMessage signal should be emitted when a new
-           debug message is generated.</p>
+    <property name="Enabled" type="b" access="readwrite"
+      tp:name-for-bindings="Enabled">
+      <tp:docstring>
+        TRUE if the <tp:member-ref>NewDebugMessage</tp:member-ref> signal
+        should be emitted when a new debug message is generated.
       </tp:docstring>
     </property>
 
-    <method name="GetMessages">
-      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>Retrieve buffered debug messages.</p>
+    <method name="GetMessages" tp:name-for-bindings="Get_Messages">
+      <tp:docstring>
+        Retrieve buffered debug messages. An implementation could have a
+        limit on how many message it keeps and so the array returned from
+        this method should not be assumed to be all of the messages in
+        the lifetime of the service.
       </tp:docstring>
 
-      <arg direction="out" name="messages" type="a(dsus)">
-         <tp:docstring>
-          A list of timestamped debug messages.
+      <arg direction="out" name="Messages" type="a(dsus)"
+        tp:type="Debug_Message[]">
+        <tp:docstring>
+          A list of debug messages.
         </tp:docstring>
       </arg>
     </method>
 
     <signal name="NewDebugMessage" tp:name-for-bindings="New_Debug_Message">
       <tp:docstring>
-        Emitted when a debug messages is generated if the Enabled property is
-        set.
+        Emitted when a debug messages is generated if the
+        <tp:member-ref>Enabled</tp:member-ref> property is set to TRUE.
       </tp:docstring>
 
       <arg name="time" type="d">
         <tp:docstring>
-          Message timestamp
+          Timestamp of the debug message.
         </tp:docstring>
       </arg>
       <arg name="domain" type="s">
-	<tp:docstring>
-	  Message domain
-	</tp:docstring>
+        <tp:docstring>
+          Domain of the debug message, as described in the Debug_Message struct.
+        </tp:docstring>
       </arg>
       <arg name="level" type="u" tp:type="Debug_Level">
-	<tp:docstring>
-	  Message level
-	</tp:docstring>
+        <tp:docstring>
+          Level of the debug message.
+        </tp:docstring>
       </arg>
       <arg name="message" type="s">
         <tp:docstring>
-          Message
+          The text of the debug message.
         </tp:docstring>
       </arg>
     </signal>
 
     <tp:enum name="Debug_Level" type="u">
       <tp:enumvalue suffix="Error" value="0">
-	<tp:docstring>
-	  error
-	</tp:docstring>
+        <tp:docstring>
+          Log level for errors. Error messages are always fatal, resulting
+          in the service terminating after something completely
+          unexpected occurred.
+        </tp:docstring>
       </tp:enumvalue>
       <tp:enumvalue suffix="Critical" value="1">
-	<tp:docstring>
-	  criticla
-	</tp:docstring>
+        <tp:docstring>
+          Log level for critical messages. Critical messages are messages
+          that the service might predict and it is up to the service itself
+          to decide whether to terminate following a critical message.
+        </tp:docstring>
       </tp:enumvalue>
       <tp:enumvalue suffix="Warning" value="2">
-	<tp:docstring>
-	  warning
-	</tp:docstring>
+        <tp:docstring>
+          Log level for warnings.
+        </tp:docstring>
       </tp:enumvalue>
       <tp:enumvalue suffix="Message" value="3">
-	<tp:docstring>
-	  message
-	</tp:docstring>
+        <tp:docstring>
+          Log level for messages.
+        </tp:docstring>
       </tp:enumvalue>
       <tp:enumvalue suffix="Info" value="4">
-	<tp:docstring>
-	  info
-	</tp:docstring>
+        <tp:docstring>
+          Log level for information messages.
+        </tp:docstring>
       </tp:enumvalue>
       <tp:enumvalue suffix="Debug" value="5">
-	<tp:docstring>
-	  debug
-	</tp:docstring>
+        <tp:docstring>
+          Log level for debug messages.
+        </tp:docstring>
       </tp:enumvalue>
     </tp:enum>
 
+    <tp:struct name="Debug_Message" array-name="Debug_Message_List">
+      <tp:docstring>
+        A struct representing a debug message, as returned by
+        <tp:member-ref>GetMessages</tp:member-ref>.
+      </tp:docstring>
+
+      <tp:member type="d" name="Timestamp">
+        <tp:docstring>
+          Timestamp of the debug message. This is a double to allow
+          more accuracy in the time the message was logged.
+        </tp:docstring>
+      </tp:member>
+
+      <tp:member type="s" name="Domain">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>Domain of the debug message. This is used to identify
+          the source of debug messages. For example, debug messages
+          from a connection manager could have this Domain struct
+          member be the name of the connection manager, and logs
+          from any helper library could have the name of the helper
+          library.</p>
+
+          <p>The domain could also contain a category as to where
+          the log message originated separated by a forward-slash.
+          For example, if a debug message was output in a connection
+          manager called "dummy", in the file-transfer code, this
+          Domain struct member might be <tt>dummy/file-transfer</tt>.</p>
+        </tp:docstring>
+      </tp:member>
+
+      <tp:member type="u" tp:type="Debug_Level" name="Level">
+        <tp:docstring>
+          Level of the debug message. This states the severity of the
+          debug message.
+        </tp:docstring>
+      </tp:member>
+
+      <tp:member type="s" name="Message">
+        <tp:docstring>
+          The text of the debug message.
+        </tp:docstring>
+      </tp:member>
+    </tp:struct>
+
   </interface>
 </node>
 <!-- vim:set sw=2 sts=2 et ft=xml: -->