Date: Sat Jul 14 16:34:08 CEST 2007
User: Derick Rethans
Directory: dbgp
Log Message:
[4.00]
- Update text after Dave's comments.
Modified files:
dbgp/debugger_protocol.txt (version: 1.9)
[FILE: /dbgp/debugger_protocol.txt]
===================================================================
RCS file: cvstemp,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- dbgp/debugger_protocol.txt:1.8 Sat Mar 31 16:01:43 2007 GMT
+++ dbgp/debugger_protocol.txt Sat Jul 14 12:34:08 2007 GMT
@@ -2,7 +2,7 @@
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:Version: 1.0
-:Status: draft 15
+:Status: draft 16
:Authors: - Shane Caraveo, ActiveState <shanec[@]ActiveState.com>
- Derick Rethans <derick[@]derickrethans.nl>
@@ -438,15 +438,14 @@
A debugging IDE (IDE) sends commands to the debugger engine in
the form of command line arguments. One argument that is included in
all commands is the data length. The data itself is the last part of
-the command line. The data may be binary data if the encoding argument
-is 'binary'. ::
+the command line, after the -- separator. The data must be base64 encoded. ::
- command [SPACE] [arguments] [SPACE] base64(data) [NULL]
+ command [SPACE] [arguments] [SPACE] -- base64(data) [NULL]
Standard arguments for all commands ::
-i Transaction ID
- unique for each command generated by the IDE
+ unique numerical ID for each command generated by the IDE
6.4 debugger engine to IDE communications
-----------------------------------------
@@ -505,10 +504,11 @@
0 - no error
1 - parse error in command
2 - duplicate arguments in command
- 3 - invalid options (ie, missing a required option)
+ 3 - invalid options (ie, missing a required option, invalid value for a
+ passed option)
4 - Unimplemented command
5 - Command not available (Is used for async commands. For instance
- if the engine is in state "run" than only "break" and "status"
+ if the engine is in state "run" then only "break" and "status"
are available).
100 File related errors ::
@@ -667,8 +667,10 @@
language_supports_threads get [0|1]
language_name get {eg. PHP, Python, Perl}
language_version get {version string}
- encoding get current encoding in use by
- the debugger session
+ encoding get current encoding in use by the debugger
+ session. The encoding can either be
+ (7-bit) ASCII, or a code set which
+ contains ASCII (Ex: ISO-8859-X, UTF-8)
protocol_version get {for now, always 1}
supports_async get {for commands such as break}
data_encoding get optional, allows to turn off
@@ -754,6 +756,17 @@
supported encodings
</response>
+The 'supported' attribute does NOT mean that the feature is supported, this
+is encoded in the text child of the response tag. The 'supported' attribute
+informs whether the feature with 'feature_name' is supported by feature_get
+in the engine, or when the command with name 'feature_get' is supported by the
+engine.
+
+Example: Xdebug does not understand the 'breakpoint_languages' feature
+and will therefore set the supported attribute to '0'. It does however
+understand the feature 'language_supports_threads' and the 'supported'
+attribute is therefore set to '1', but as PHP does not support threads,
+the returned value is in this case "0".
7.2.3 feature_set
^^^^^^^^^^^^^^^^^
@@ -888,8 +901,8 @@
return function break on exit from stack for function
name
exception exception break on exception of the given name
- conditional expression break when the given expression is true
- at the given filename and line number or
+ conditional expression, break when the given expression is true
+ filename at the given filename and line number or
just in given filename
watch expression break on write of the variable or address
defined by the expression argument
@@ -902,7 +915,8 @@
================== ======================================================
type breakpoint type (see table above for valid types)
filename The file the breakpoint is effective in. This must be
- a "file://" URI.
+ a "file://" or "dbgp:" (See `6.7 Dynamic code and
+ virtual files`_) URI.
lineno Line number on which breakpoint is effective. Line
numbers are 1-based. If an implementation requires a
numeric value to indicate that *lineno* is not set,
@@ -988,7 +1002,9 @@
-r 0|1 Boolean value indicating if this breakpoint is
*temporary*. [optional, defaults to false]
-- EXPRESSION code *expression*, in the language of the debugger
- engine [required for *conditional* breakpoint types]
+ engine. The breakpoint should activate when the
+ evaluated code evaluates to *true*. [required for
+ *conditional* breakpoint types]
================== =====================================================
An example breakpoint_set command for a conditional breakpoint could look
@@ -998,7 +1014,10 @@
A unique id for this breakpoint for this session is returned by the debugger
engine. This *session breakpoint id* is used by the IDE to identify the
-breakpoint in other breakpoint commands.
+breakpoint in other breakpoint commands. It is up to the engine on how
+to handle multiple "similar" breakpoints, such as a double breakpoint
+on a specific file/line combination - even if other parameters such as
+hit_value/hit_condition are different.
debugger engine to IDE::
@@ -1088,7 +1107,9 @@
7.6.4 breakpoint_remove
^^^^^^^^^^^^^^^^^^^^^^^
-This command is used by the IDE to remove the given breakpoint.
+This command is used by the IDE to remove the given breakpoint. The
+debugger engine can optionally embed the remove breakpoint as child
+element.
IDE to debugger engine::
@@ -1221,7 +1242,7 @@
The names of currently available contexts at a given stack depth,
typically Local, Global and Class. These SHOULD be UI friendly
-names. The id attribute returned with the names is used in other
+names. The numerical id attribute returned with the names is used in other
commands such as context_get to identify the context. The context
id zero is always considered to be the 'default' context is no
context id is provided. In most languages, this will the be
@@ -1329,7 +1350,8 @@
located. The page number is 0-based.
pagesize the size of each page of data, defaulted by the
debugger engine, or negotiated with feature_set
- and max_children
+ and max_children. Required when the page attribute
+ is available.
type language specific data type name
facet provides a hint to the IDE about additional
facets of this value. These are space separated
@@ -1342,8 +1364,8 @@
the property.
key language dependent reference for the property.
if the key is available, the IDE SHOULD use it
- to retrieve further data for the property
- address containing physical memory address
+ to retrieve further data for the property, optional
+ address containing physical memory address, optional
encoding if this is binary data, it should be base64 encoded
with this attribute set
=============== ========================================================
@@ -1526,15 +1548,16 @@
debugger engine should assume zero if not provided)
-n property long name (required)
-m max data size to retrieve (optional)
- -t data type (optional)
- -p data page (optional, for arrays, hashes, objects, etc.)
+ -t data type (property_set only, optional)
+ -p data page (property_get, property_value: optional for arrays,
+ hashes, objects, etc.; property_set: not required; debugger
+ engine should assume zero if not provided)
-k property key as retrieved in a property element,
optional, used for property_get of children and
property_value, required if it was provided by the
debugger engine.
-a property address as retrieved in a property element,
- optional, used for property_set/value, required if it
- was provided by the debugger engine.
+ optional, used for property_set/value
== ========================================================
IDE ::
@@ -1940,10 +1963,10 @@
debugger output window.
A new feature name is introduced: notify_ok. The IDE will call feature_set
-with the notify_ok name and a TRUE value. This lets the debugger engine know
-that it can send notifications to the IDE. If the IDE has not set this value,
-or sets it to FALSE, then the debugger engine MUST NOT send notifications to
-the IDE.
+with the notify_ok name and a TRUE value (1). This lets the debugger engine
+know that it can send notifications to the IDE. If the IDE has not set this
+value, or sets it to FALSE (0), then the debugger engine MUST NOT send
+notifications to the IDE.
The debugger engine MUST NOT expect a notification to cause an IDE to behave
in any particular way, or even to be handled by the IDE at all.
@@ -1955,7 +1978,7 @@
IDE initialization of notifications::
- feature_set -i TRANSACTION_ID -n notify_ok -- base64(1)
+ feature_set -i TRANSACTION_ID -n notify_ok -v 1
debugger engine notifications to IDE::
@@ -2020,7 +2043,7 @@
or some other string to denote a console stack level.
The debugger engine is not required to enable debugging of code
-recieved via the interact command, however it should provide access
+received via the interact command, however it should provide access
to other information, such as the variables retrieved via context_get.
IDE to debugger engine::
@@ -2071,6 +2094,31 @@
A. ChangeLog
============
+2007-07-14 - draft 16
+
+- 6.3 Fixed binary encoding comments regarding data.
+- 6.3 Clarified that the transaction ID is supposed to be numerical.
+- 6.5.1 Mention that error code three is also for "invalid values to an
+ option".
+- 7.2.1 Clarified encoding feature.
+- 7.2.2 Clarified the supported attribute for feature_get.
+- 7.6 Added missing required attribute "filename" to the "conditional"
+ breakpoint type.
+- 7.6 Added missing "dbgp:" URI scheme to "filename" breakpoint option.
+- 7.6.1 Added a comment that it is up to the engine on how to handle
+ duplicate breakpoints.
+- 7.6.1 Clarified on how expression evaluations affect breakpoint activation.
+- 7.6.4 Added Xdebug's practise of returning the deleted breakpoint's
+ information as an optional child element.
+- 7.9 Clarified that the context's ID attributes are numerical.
+- 7.11 Marked "key" and "address" attributes as "optional
+- 7.13 The -a option is not required if the address is provided. Implementation
+ of this option could possible allow reading at random memory addresses which
+ is a security issue.
+- 7.13 Clarified on how the -p option is used.
+- 8.5 Fixed feature_set command in example, it does not use command data, but
+ the -v option for specifying the value.
+
2007-03-31
- 7.6.1 Fixed breakpoint_set example and note that the breakpoint types
Received on Sat Jul 14 2007 - 16:34:15 BST
This archive was generated by hypermail 2.2.0 : Sun Jun 24 2018 - 04:00:03 BST