Skip to content

Features

Jump to bottom
kevindawson edited this page Nov 1, 2012 · 11 revisions

Features < DBGp 7.2 >

Q do we want to impose the get|set method attribute prefix

1. Compulsory

  • max_depth - maximum depth that the debugger engine may return when sending arrays, hashs or object structures to the IDE.

1. Optional

  • supports_async -

1. Example

Get max_depth

  • Send
{
   "feature_get" : "max_depth"
}
  • Response
{
   "response" : {
      "max_depth" : "4",
   }
}

Set max_depth

  • Send
{
   "feature_set" : "max_depth",
   "depth" : "6"
}
  • Response
{
   "response" : {
      "max_depth" : "6",
   }
}

Error

{
   "response" : {
      "max_depth" : "error",
      "error" : "nn",
   }
}

< DBGp 7.2 Options and Configuration >

The feature commands are used to request feature support from the debugger engine. This includes configuration options, some of which may be changed via feature_set, the ability to discover support for implemented commands, and to discover values for various features, such as the language version or name.

An example of usage would be to send a feature request with the string 'stdin' to find out if the engine supports redirection of the stdin stream through the debugger socket. The debugger engine must consider all commands as keys for this command, but may also have keys that are for features that do not map directly to commands.

7.2.1 Feature Names

The following features strings MUST be available:

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. 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 the default base64 encoding of data. This should only be used for development and debugging of the debugger engines themselves, and not for general use. If implemented the value 'base64' must be supported to turn back on regular encoding. the value 'none' means no encoding is in use. all elements that use encoding must include an encoding attribute.
breakpoint_languages 	get 	some engines may support more than one language. This feature returns a string which is a comma separated list of supported languages. If the engine does not provide this feature, then it is assumed that the engine only supports the language defined in the feature language_name. One example of this is an XSLT debugger engine which supports XSLT, XML, HTML and XHTML. An IDE may need this information to to know what types of breakpoints an engine will accept.
breakpoint_types 	get 	returns a space separated list with all the breakpoint types that are supported. See 7.6 breakpoints for a list of the 6 defined breakpoint types.
multiple_sessions 	get|set 	{0|1}
encoding 	get|set 	{ISO8859-15, UTF-8, etc.}
max_children 	get|set 	max number of array or object children to initially retrieve
max_data 	get|set get|set 	max amount of variable data to initially retrieve.
max_depth 	get|set 	maximum depth that the debugger engine may return when sending arrays, hashs or object structures to the IDE.

The following features strings MAY be available, if they are not, the IDE should assume that the feature is not available:

supports_postmortem 	get 	[0|1] This feature lets an IDE know that there is benefit to continuing interaction during the STOPPING state (sect. 7.1).
show_hidden 	get|set 	[0|1] This feature can get set by the IDE if it wants to have more detailed internal information on properties (eg. private members of classes, etc.) Zero means that hidden members are not shown to the IDE.
notify_ok 	get|set 	[0|1] See section 8.5

Additionally, all protocol commands supported must have a string, such as the following examples:

breakpoint_set
break
eval

7.2.2 feature_get

arguments for feature_get include:

-n 	feature_name

IDE

feature-get -i transaction_id -n feature_name

debugger engine

<response command="feature_get"
          feature_name="feature_name"
          supported="0|1"
          transaction_id="transaction_id">
    feature setting or available options, such as a list of
    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

The feature set command allows a IDE to tell the debugger engine what additional capabilities it has. One example of this would be telling the debugger engine whether the IDE supports multiple debugger sessions (for threads, etc.). The debugger engine responds with telling the IDE whether it has enabled the feature or not.

Note: The IDE does not have to listen for additional debugger connections if it does not support debugging multiple sessions. debugger engines must handle connection failures gracefully.

arguments for feature_set include:

-n 	feature_name
-v 	value to be set

feature_set can be called at any time during a debug session to change values previously set. This allows a IDE to change encodings.

IDE

feature_set -i transaction_id -n feature-name -v value

debugger engine

<response command="feature_set"
          feature="feature_name"
          success="0|1"
          transaction_id="transaction_id"/>
Clone this wiki locally