<html>

<head>
<title>Java(tm) Debug Wire Protocol Transport Interface (jdwpTransport) </title>
</head>

<body BGCOLOR=white LINK=blue VLINK=blue ALINK=red>
<p>  
<table border="0" width="100%" summary="layout">
<tbody><tr>
<td width="60"><img src="../../images/javalogo52x88.gif" width="52" height="88" align="bottom" alt="Java" border="0"> </td>
<td>
<h1 align="center">Java<font size="1"><sup>TM</sup></font> Debug Wire Protocol Transport Interface (jdwpTransport)
		</h1></td>
<td width="60" align="right" valign="top">
<p align="right"><a href="../../index.html"><font size="2">Documentation Contents</font></a>
</p></td>
</tr>
</tbody></table>


<p>A transport is implemented as a series of functions in a dynamic library
(sometimes called a <i>DLL</i>, or <i>shared library</i>). The library
exports an <i>onload</i> function that is invoked by the JDWP (or other) agent at 
startup-time.

<p>Like JVMTI, jdwpTransport functions are accessed through an interface pointer
called the <i>environment pointer</i>. An environment pointer is a pointer to an
environment and has type <tt>jdwpTransportEnv*</tt>. The environment pointer is
returned to the JDWP (or other) agent from the <i>onload</i> function.

<p>A transport may support a single environment or it may support
multiple environments. In other words, a transport may be used by only one, or multiple 
agents at the same time. If a transport supports multiple environments then each call to 
the <i>onload</i> function will return a new environment pointer. If a transport only 
supports a single environment then second, and subsequent calls to the <i>onload</i>
function will return an error.

<p>A transport is thread-safe and jdwpTransport functions can be used
by multiple concurrent threads. For example, one thread may be blocked in
the jdwpTransport <tt>ReadPacket</tt> function waiting for a packet while another
thread invokes <tt>WritePacket</tt> function to write a packet.

<p>In most cases jdwpTransport functions return a <tt>jdwpTransportError</tt>
value indicating return status. Some functions return additional values through
pointers provided by the calling function. In cases where the return values are
allocated by a jdwpTransport function then the function will use the memory
allocation routine specified by the agent. The memory allocation routines are
specified to the transport, at start-up, via the <i>onload</i> function.
  
<p>In the event of an error (that is, one of the jdwpTransport functions
returns a value other than <tt>JDWPTRANSPORT_ERROR_NONE</tt>) then a 
string representing the error can be subsequently obtained through a call
to the jdwpTransport function <tt>GetLastError</tt>. Errors are recorded on a
per-thread basis. The <tt>GetLastError</tt> function will return a string 
represetning the last error that was encountered by the current thread only.
</p>


<h2>Developing a Transport implementation</h2>

<p>A transport library can be developed in any native language that supports C language
calling conventions and C or C++ definitions.

<p>The function, data type, and constant definitions needed for using the jdwpTransport 
interface are defined in the include file jdwpTransport.h. To use these definitions add 
the J2SE TM include directory to your include path :-

<blockquote><pre>#include "jdwpTransport.h"
</pre></blockquote>


<h2>Transport Start-Up</h2>

<p>The transport library must export an <i>onload</i> function with the following
prototype :-

<blockquote><pre>
JNIEXPORT jint JNICALL 
jdwpTransport_OnLoad(JavaVM *jvm,
                     jdwpTransportCallback *callback,
                     jint version,
                     jdwpTransportEnv** env);
</pre></blockquote>

<p>This function will be called by the JDWP (or other agent) when the library is
loaded.

<p>The <tt>jvm</tt> argument is the <i>JNI invocation interface</i> obtained by agent
by invoking JNI's <tt>GetJavaVM</tt> function.

<p>The <tt>callback</tt> argument is a pointer to a function table of memory 
management routines that the transport must use to allocate the memory for return
values that are allocated by the transport implementation :-

<blockquote><pre>
typedef struct jdwpTransportCallback {
    void* (*alloc)(jint numBytes);
    void (*free)(void *buffer);
} jdwpTransportCallback;
</pre></blockquote>

<p>The lifespan of the <tt>callback</tt> argument is the <i>onload</i> function
and therefore the transport must take a copy of the function table in the
<tt>jdwpTransport_OnLoad</tt> function. 

<p>The function table has two entries. The <tt>alloc</tt> function allocates an area 
of memory. It has a single argument to specify the number of bytes to allocate. It returns 
a pointer to the begining of the allocated memory, or NULL if the memory request cannot be
honored. If the number of bytes requested is zero then NULL is returned. 
The <tt>free</tt> function deallocates an area of memory that was previously allocated 
using the <tt>alloc</tt> function. 

<p>The memory management functions provided by the agent are thread safe and the
transport implementation is not required to synchronize calls to the these functions.
The implementation of the memory management functions are guaranteed not to call 
any jdwpTransport function.

<p><tt>version</tt> is the version of the transport interface that the agent
expects. This must be specified as <tt>JDWPTRANSPORT_VERSION_1_0</tt>.

<p><tt>env</tt> is a pointer to the environment pointer returned by the function.

<p>The <tt>jdwpTransport_OnLoad</tt> function returns <tt>JNI_OK</tt>
if the transport initializes successfully. If initialization fails then
one of the following errors is returned :-

<blockquote><pre>JNI_ENOMEM
JNI_EVERSION
JNI_EEXIST
</pre></blockquote>

<p> <tt>JNI_ENOMEM</tt> is returned if there is insufficient memory to
complete initialization.

<p> <tt>JNI_EVERSION</tt> is returned if the version in the
<tt>version</tt> argument is not <tt>JDWPTRANSPORT_VERSION_1_0</tt>.

<p> <tt>JNI_EEXIST</tt> is returned if the transport only supports a single
environment, and the environment pointer was previously returned by the
first call to the <i>onload</i> function.
</p>


<h2>Functions</h2>

<p>
The jdwpTransport functions fall into these categories:
<ul>
    <li><a href=#connection><b>Connection Management</b></a>
	   <ul>
	     	<li><a href=#Attach>Attach</a>
	     	<li><a href=#StartListening>StartListening</a>
	     	<li><a href=#StopListening>StopListening</a>
	      	<li><a href=#Accept>Accept</a>
	     	<li><a href=#IsOpen>IsOpen</a>
	 	<li><a href=#Close>Close</a>		
	   </ul>
    <li><a href=#IO><b>I/O Functions</b></a>
	  <ul>
		<li><a href=#ReadPacket>ReadPacket</a>
		<li><a href=#WritePacket>WritePacket</a>
	  </ul>
    <li><a href=#miscellaneous><b>Miscellaneous Functions</b></a>
	  <ul>
	    <li><a href=#GetLastError>GetLastError</a>
	    <li><a href=#GetCapabilities>Get Capabilities</a>
	  </ul>
</ul>


<a name="connection"></a>
<p><hr noshade size=3>
<h2>Connection Management</h2>

<p>The connection management functions are used to establish and close the connection 
to the debugger. A connection provides a reliable flow of JDWP packets to and from
the debugger. Packets written to a connection are read, by the debugger, in exactly
the order in which they were written. Similarly, any packets written to the 
connection by the debugger are read in the order in which they were written.

<p> Connections are established either <i>actively</i> or <i>passively</i>.
Establishing the connection <i>actively</i> means that the jdwpTransport's
<tt>Attach</tt> function is called to initiate the connection the debugger.
Establishing the connection <i>passively</i> means that the jdwpTransport's 
<tt>StartListening</tt> function is used to put the transport into <i>listen mode</i> so
that it listens for a connection from a debugger. Once in listen mode the
<tt>Accept</tt> function is used to accept the connection. Irrespective of how
the connection is established the <tt>Close</tt> function is used to close the
connection, and <tt>IsOpen</tt> is used to test if a connection is open to the 
debugger. 
</p>

<a name="Attach"></a>
<hr noshade width=75%>
<h3>Attach</h3>
<blockquote><pre>
jdwpTransportError
Attach(jdwpTransportEnv* env, const char* address, 
       jlong attachTimeout, jlong handshakeTimeout)
</pre></blockquote>

<p>Attaches to the debugger. Attaching to the debugger involves two steps.
First, a connection is established to the specified <tt>address</tt>.
Once a connection is established a <i>handshake</i> is performed to ensure
that the connection is indeed established to a debugger. Handshaking 
involves the exchange of ASCII string <i>JDWP-Handshake</i> as 
specified in the 
<a href="jdwp-spec.html">
Java Debug Wire Protocol</a> specification.

<p>The <tt>address</tt> argument is a pointer to a string representing the 
address of the debugger. The exact format is specific to the transport (In the
case of a TCP/IP based transport the address may include the hostname and port
number of the debugger. In the case of a transport that supports connections
through a serial port it might be the device name of the serial port).

<p>The <tt>attachTimeout</tt> argument specifies a timeout to use
when attaching. If the transport supports an attach timeout (see
<a href=#GetCapabilities>GetCapabilities</a>) and if the <tt>attachTimeout</tt>
is positive then it specifies the timeout, in milliseconds (more or less), 
to use when attaching to the debugger.  If the transport does not support 
an attach timeout, or if <tt>attachTimeout</tt> is specified as zero then 
a timeout is not used when attaching. 

<p>The <tt>handshakeTimeout</tt> argument specifies a timeout to
use when handshaking with the debugger. If the transport supports a
handshake timeout (see <a href=#GetCapabilities>GetCapabilities</a>) and
if the <tt>handshakeTimeout</tt> is positive then it specifies the timeout,
in milliseconds (more or less), to use when handshaking with the debugger.
The exact usage of the handshake timeout is specific to the transport - for 
example one implementation may use the timeout as an inter-character 
timeout while waiting for the <i>JDWP-Handshake</i> message from the
debugger. Another implementation may use the timeout to indicate the
total duration allowed for the handshake exchange. In general the
purpose of the handshake timeout is to allow for error handling in
the event that the transport connects to something other than a 
valid debugger.
If the transport does not support a handshake timeout, or if the
<tt>handshakeTimeout</tt> is specified as zero then a timeout is not
used when handshaking.

<p>This function returns a <a href=#Universal>universal error</a> or one 
of the following errors:
<blockquote><pre>
JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT
JDWPTRANSPORT_ERROR_ILLEGAL_STATE
JDWPTRANSPORT_ERROR_IO_ERROR
JDWPTRANSPORT_ERROR_TIMEOUT
</pre></blockquote>

<p><tt>JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT</tt> is returned if 
<tt>address</tt> is invalid or <tt>timeout</tt> is negative. 

<p><tt>JDWPTRANSPORT_ERROR_ILLEGAL_STATE</tt> is returned if the transport
is currently in <i>listen mode</i> (see <a href=#StartListening>StartListening</a>),
or there is already an open connection to the debugger (see 
<a href=#IsOpen>IsOpen</a>).

<p><tt>JDWPTRANSPORT_ERROR_IO_ERROR</tt> is returned if there is an error
(other than an attach timeout) attaching to the debugger. Note that 
errors during the start-up handshake (including a handshake timeout) are
considered I/O errors. I/O errors are specific to the transport.
<a href=#GetLastError>GetLastError</a> can be used to obtain a string
representation of the error.

<p><tt>JDWPTRANSPORT_ERROR_TIMEOUT</tt> is returned if the transport supports
an attach timeout, and if the <tt>attachTimeout</tt> value is positive, and if
the connection to the debugger cannot be established within that attachTimeout
period.

<a name="StartListening"></a>
<hr noshade width=75%>
<h3>StartListening</h3>
<blockquote><pre>
jdwpTransportError
StartListening(jdwpTransportEnv* env, const char* address, char** actualAddress);
</pre></blockquote>

<p>Puts the transport into <i>listen mode</i> to listen for a connection
from a debugger.

<p>The <tt>address</tt> argument is a pointer to a string representing the local
address that the transport should listen on. The exact format is specific to the 
transport (In the case of a TCP/IP based transport the address might a local
TCP port number. In the case of a transport that supports connections
through a serial port it might be the device name of a serial port). The 
<tt>address</tt> argument can be specified as <tt>NULL</tt> or as 
an empty string (first character is <tt>\0</tt>). In that case the 
transport listens on a default address that is specific to the transport.


<p>If <tt>actualAddress</tt> is not <tt>NULL</tt> then it is set to the
address of a string returned by the <tt>StartListening</tt> function.
The returned string will contain the string representation of the 
address that the transport is listening on. This may, or may not, differ
from the address provided in the <tt>address</tt> argument. 
The string is allocated using the allocation callback provided to the
transport when the <tt>jdwpTransport_OnLoad</tt> function was called. The
caller is responsible for freeing the returned string.

<p>This function returns a <a href=#Universal>universal error</a> or one
of the following errors:
<blockquote><pre>
JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT
JDWPTRANSPORT_ERROR_ILLEGAL_STATE
JDWPTRANSPORT_ERROR_IO_ERROR
</pre></blockquote>

<p><tt>JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT</tt> is returned if 
<tt>address</tt> is invalid.

<p><tt>JDWPTRANSPORT_ERROR_ILLEGAL_STATE</tt> is returned if there is already
an open connection to a debugger (see <a href=#IsOpen>IsOpen</a>), or
the transport is already in listen mode.

<p><tt>JDWPTRANSPORT_ERROR_IO_ERROR</tt> is returned if there is an error
putting the transport into listen mode. The nature of the error
is specific to the transport. <a href=#GetLastError>GetLastError</a> can
be used to obtain a  string representing the error. </p>

<a name="StopListening"></a>
<hr noshade width=75%>
<h3>StopListening</h3>
<blockquote><pre>
jdwpTransportError
StopListening(jdwpTransportEnv* env)
</pre></blockquote>

<p>Takes the transport out of <i>listen mode</i> so that it's no longer
listening for connections from a debugger.

<p>If the transport is in <i>listen mode</i> then it will be taken out of
this mode. If there is an open (see <a href=#IsOpen>IsOpen</a>) connection
to a debugger then it is unaffected by this function. In other words, 
<tt>StopListening</tt> does not close a connection to the debugger. If the
transport is not in listen mode then this function does nothing and no
error is returned.

<p>This function returns a <a href=#Universal>universal error</a> or one
of the following errors:
<blockquote><pre>
JDWPTRANSPORT_ERROR_IO_ERROR
</pre></blockquote>

<p><tt>JDWPTRANSPORT_ERROR_IO_ERROR</tt> is returned if there is an error
taking the transport out of listen mode. The nature of the error
is specific to the transport. <a href=#GetLastError>GetLastError</a> can
be used to obtain a  string representing the error. </p>


<a name="Accept"></a>
<hr noshade width=75%>
<h3>Accept</h3>
<blockquote><pre>
jdwpTransportError
Accept(jdwpTransportEnv* env, jlong acceptTimeout, jlong handshakeTimeout)
</pre></blockquote>

<p>Accepts a connection from a debugger. Accepting a connection from
a debugger involves two steps. Firstly, a connection is established by
the debugger. Once a connection is established a <i>handshake</i> is 
performed to ensure that the connection was indeed established by a
debugger. Handshaking involves the exchange of ASCII string
<i>JDWP-Handshake</i> as specified in the
<a href="jdwp-spec.html">
Java Debug Wire Protocol</a> specification.

<p>The <tt>acceptTimeout</tt> argument specifies the timeout to use while
waiting for the debugger to connect. If the transport supports an accept
timeout (see <a href=#GetCapabilities>GetCapabilities</a>) and if 
the <tt>acceptTimeout</tt> is positive then it specifies the timeout,
in milliseconds (more or less), 
to use when waiting for a connection from a debugger.  If the transport does not 
support an accept timeout, or if <tt>timeout</tt> is specified as zero then 
block indefinitely waiting for a connection.

<p>The <tt>handshakeTimeout</tt> argument specifies a timeout to
use when handshaking with the debugger. If the transport supports a
handshake timeout (see <a href=#GetCapabilities>GetCapabilities</a>) and
if the <tt>handshakeTimeout</tt> is positive then it specifies the timeout,
in milliseconds (more or less), to use when handshaking with the debugger.
The exact usage of the handshake timeout is specific to the transport - for
example one implementation may use the timeout as an inter-character
timeout while waiting for the <i>JDWP-Handshake</i> message from the
debugger. Another implementation may use the timeout to indicate the
total duration allowed for the handshake exchange. In general the
purpose of the handshake timeout is to allow for error handling in
the event that something other than a debugger establishes a connection
to the debuggee.
If the transport does not support a handshake timeout, or if the
<tt>handshakeTimeout</tt> is specified as zero then a timeout is not
used when handshaking.

<p>This function returns a <a href=#Universal>universal error</a> or one
of the following errors:
<blockquote><pre>
JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT
JDWPTRANSPORT_ERROR_ILLEGAL_STATE
JDWPTRANSPORT_ERROR_IO_ERROR
JDWPTRANSPORT_ERROR_TIMEOUT
</pre></blockquote>

<p><tt>JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT</tt> is returned if 
<tt>attachTimeout</tt> or <tt>handshakeTimeout</tt> is negative. 

<p><tt>JDWPTRANSPORT_ERROR_ILLEGAL_STATE</tt> is returned if there is already
an open connection to a debugger (see <a href=#IsOpen>IsOpen</a>), or if
the transport is not in listen mode (see <a href=#StartListening>StartListening</a>).

<p><tt>JDWPTRANSPORT_ERROR_IO_ERROR</tt> is returned if there is an error
(other than an accept timeout) while accepting a connection from a debugger. 
Note that errors during the start-up handshake (including a handshake timeout) are
considered I/O errors.  
The nature of the error is specific to the transport.
<a href=#GetLastError>GetLastError</a> can be used to obtain a  string 
representing the error.

<p><tt>JDWPTRANSPORT_ERROR_TIMEOUT</tt> is returned if the transport supports
an accept timeout, and if the <tt>acceptTimeout</tt> value is positive, and if
the connection to the debugger cannot be established within that timeout
period.

<p><b>Note:</b> A thread that is blocked in <tt>Accept</tt> waiting for a
connection from a debugger can be interrupted by another thread calling
<tt>StopListening</tt>. In that case the thread that called <tt>Accept</tt>
will return <tt>JDWPTRANSPORT_ERROR_IO_ERROR</tt> indicating an I/O
error has occurred. If a thread blocked in <tt>Accept</tt> has accepted
a connection and is in the process of handshaking with the debugger then
<tt>StopListening</tt> will not interrupt the connection.

<a name="IsOpen"></a>
<hr noshade width=75%>
<h3>IsOpen</h3>
<blockquote><pre>
jboolean
isOpen(jdwpTransportEnv* env)
</pre></blockquote>

<p>Tells whether or not there is a connection open to a debugger.

<p>Returns <tt>JNI_TRUE</tt> if, and only if, there is an open connection
to a debugger. Otherwise it returns <tt>JNI_FALSE</tt>. </p>


<a name="Close"></a>
<hr noshade width=75%>
<h3>Close</h3>
<blockquote><pre>
jdwpTransportError
Close(jdwpTransportEnv* env)
</pre></blockquote>

<p>Closes an open connection to a debugger. 

<p>If there isn't an open connection to a debugger (see <a href=#IsOpen>IsOpen</a>)
then this function does nothing and no error is returned.

<p>If there are threads blocked in any I/O functions (namely, 
<a href=#ReadPacket>ReadPacket</a> and <a href=#WritePacket>WritePacket</a>),
then these I/O functions will be interrupted by the close and will return
an <tt>JDWPTRANSPORT_ERROR_IO_ERROR</tt> indicating an I/O error has
occurred.

<p>This function returns a <a href=#Universal>universal error</a> or one
of the following errors:
<blockquote><pre>
JDWPTRANSPORT_ERROR_IO_ERROR
</pre></blockquote>

<p><tt>JDWPTRANSPORT_ERROR_IO_ERROR</tt> is returned if there is an error
closing the connection. The nature of the error is specific to the transport. 
<a href=#GetLastError>GetLastError</a> can be used to obtain a  string 
representing the error. </p>




<a name="IO"></a>
<p><hr noshade size=3>
<h2>I/O Functions</h2>

<p>The I/O functions are used for reading and writing JDWP packets from and
to the debugger.

<a name="ReadPacket"></a>
<hr noshade width=75%>
<h3>ReadPacket</h3>
<blockquote><pre>

typedef struct {
    jint len; 
    jint id;
    jbyte flags;
    jbyte cmdSet;
    jbyte cmd;
    jbyte *data;
} jdwpCmdPacket;

typedef struct {
    jint len;
    jint id;
    jbyte flags;
    jshort errorCode;
    jbyte *data;
} jdwpReplyPacket;

typedef struct jdwpPacket {
    union {
        jdwpCmdPacket cmd;
        jdwpReplyPacket reply;
    } type;
} jdwpPacket;

jdwpTransportError
ReadPacket(jdwpTransportEnv* env, jdwpPacket* packet)
</pre></blockquote>

<p>Reads a JDWP packet from an open connection to a debugger.

<p>This function does a <i>blocking read</i> on an open connection. It
blocks indefinitely until a complete JDWP packet can be returned, or in the
case of a transport based on a stream-oriented protocol, end-of-stream is
encountered.

<p>The <tt>packet</tt> argument is the address of a <tt>jdwpPacket</tt> structure
that is populated by this function. The <tt>packet.type.cmd.len</tt> or
<tt>packet.type.reply.len</tt> field (depending on if the packet is a command
or reply packet) is populated with the length of the packet.
If end of stream is encountered the length field will be set to <tt>0</tt> and
all other fields in the packet will be undefined. If end of stream is encountered
after reading some, but not all, bytes of a packet it is considered an I/O
error and <tt>JDWPTRANSPORT_ERROR_IO_ERROR</tt> will be returned. In that
case the length field will not be populated. When an entire packet is read
then all fields in the packet are populated with values in host order.
This may, or may not, differ from the big endian order require when
transmitting JDWP packets.

<p> The <tt>packet.type.cmd.data</tt> or <tt>packet.type.reply.data</tt> field 
(depending on if the packet is a command or reply packet) will be populated 
with <tt>NULL</tt> or a pointer to the packet data allocated by this function. 
Packet data is allocated using the allocation callback provided to the
transport when the <tt>jdwpTransport_OnLoad</tt> function was called. The
caller is responsible to free it. The layout of the packet data (that
is the data following the header, if any) is returned to the caller 
in the byte ordering in which it was received. 

<p> The <tt>ReadPacket</tt> function does not do any integrity checking on
the returned packet except checking that the length of the packet
(as indicated by the first 4 bytes) is <tt>>=</tt> 11 bytes. If the 
<tt>length</tt> field is less than 11 bytes then 
<tt>JDWPTRANSPORT_ERROR_IO_ERROR</tt> is returned.

<p>This function returns a <a href=#Universal>universal error</a> or one
of the following errors:
<blockquote><pre>
JDWPTRANSPORT_ERROR_IO_ERROR
JDWPTRANSPORT_ERROR_ILLEGAL_STATE
JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT
</pre></blockquote>

<p><tt>JDWPTRANSPORT_ERROR_IO_ERROR</tt> is returned if an I/O error occurs
when reading, the connection is closed asynchronously by another thread calling the 
<a href=#Close>Close</a> function, or a badly formed packet (<tt>length</tt>
field less than 11 bytes) is received. I/O errors are specific to the 
transport. <a href=#GetLastError>GetLastError</a> can be used to obtain 
a  string representing the error. </p>

<p><tt>JDWPTRANSPORT_ERROR_ILLEGAL_STATE</tt> is returned if there isn't an open
connection to a debugger (see <a href=#IsOpen>IsOpen</a>). </p>

<p><tt>JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT</tt> is returned if
 <tt>packet</tt> is <tt>NULL</tt>



<a name="WritePacket"></a>
<hr noshade width=75%>
<h3>WritePacket</h3>
<blockquote><pre>
jdwpTransportError
WritePacket(jdwpTransportEnv* env, const jdwpPacket* packet)
</pre></blockquote>

<p>Writes a JDWP packet to an open connection.

<p>The <tt>packet</tt> argument is a pointer to a <tt>jdwpPacket</tt> structure.
All fields in the packet header must be stored in host order. 
The packet data field
(<tt>packet.type.cmd.data</tt> or <tt>packet.type.reply.data</tt>) must
be <tt>NULL</tt>, or a pointer to a location containing packet data
that immediately follows the header.
The packet data is must be in network order (big endian) ready for
transmission.

<p>This function returns a <a href=#Universal>universal error</a> or one
of the following errors:
<blockquote><pre>
JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT
JDWPTRANSPORT_ERROR_IO_ERROR
JDWPTRANSPORT_ERROR_ILLEGAL_STATE
</pre></blockquote>

<p><tt>JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT</tt> if <tt>packet</tt> is
<tt>NULL</tt>, or if the packet length field
(<tt>packet.type.cmd.len</tt> or <tt>packet.type.reply.len</tt>)
is less than 11, or it is greater than 11 but the packet data field
(<tt>packet.type.cmd.data</tt> or <tt>packet.type.reply.data</tt>) is
<tt>NULL</tt>.

<p><tt>JDWPTRANSPORT_ERROR_IO_ERROR</tt> is returned if an I/O error occurs
when writing, or the connection is closed asynchronously by another thread 
calling the <a href=#Close>Close</a> function. I/O errors are specific to the 
transport. <a href=#GetLastError>GetLastError</a> can be used to obtain 
a  string representing the error. </p>

<p><tt>JDWPTRANSPORT_ERROR_ILLEGAL_STATE</tt> is returned if there isn't an open
connection to a debugger (see <a href=#IsOpen>IsOpen</a>). </p>





<a name="miscellaneous"></a>
<p><hr noshade size=3>
<h2>Miscellaneous Functions</h2>


<a name="GetLastError"></a>
<hr noshade width=75%>
<h3>GetLastError</h3>

<blockquote><pre>
jdwpTransportError
GetLastError(jdwpTransportEnv* env, char** msg);
</pre></blockquote>

<p>Returns the  string representation of the last error.

<p>When an error occurs it is recorded on a per-thread basis. A subsequent
call to <tt>GetLastError</tt> returns the  string
representation of the last I/O error.

<p>The <tt>msg</tt> argument is a pointer to a null-terminated string returned by this
function. The string is allocated using the allocation callback provided to 
the transport when the <tt>jdwpTransport_OnLoad</tt> function was called. The
caller is responsible to free the returned string.


<p>This function returns a <a href=#Universal>universal error</a> or one
of the following errors:
<blockquote><pre>
JDWPTRANSPORT_ERROR_MSG_NOT_AVAILABLE
</pre></blockquote>

<p><tt>JDWPTRANSPORT_ERROR_MSG_NOT_AVAILABLE</tt> is returned if this thread
has not encountered an I/O error or there isn't a string representation of 
the last error available. 


<a name="GetCapabilities"></a>
<hr noshade width=75%>
<h3>GetCapabilities</h3>

<blockquote><pre>

typedef struct {
    unsigned int can_timeout_attach	:1;
    unsigned int can_timeout_accept	:1;
    unsigned int can_timeout_handshake  :1;
    unsigned int reserved3		:1;
    unsigned int reserved4		:1;
    unsigned int reserved5		:1;
    unsigned int reserved6		:1;
    unsigned int reserved7		:1;
    unsigned int reserved8		:1;
    unsigned int reserved9		:1;
    unsigned int reserved10		:1;
    unsigned int reserved11		:1;
    unsigned int reserved12		:1;
    unsigned int reserved13		:1;
    unsigned int reserved14		:1;    
    unsigned int reserved15		:1;
} JDWPTransportCapabilities;

jdwpTransportError
GetCapabilities(jdwpTransportEnv* env, JDWPTransportCapabilities* capabilitiesPtr)

</pre></blockquote>

<p>Returns via <tt>capabilitiesPtr</tt> the optional jdwpTransport features supported 
by this transport. The  capabilities structure contains a number of boolean flags 
indicating whether the named feature is supported. The current set of flags is:

<p>
<TABLE BORDER="0" WIDTH="100%">
  <TR>
    <TD><tt>can_timeout_attach</tt></TD>
    <TD>Indicates if the transport supports attaching with a timeout</TD>
  </TR>
  <TR>
    <TD><tt>can_timeout_accept</tt></TD>
    <TD>Indicates if the transport supports an accept timeout </TD>
  </TR>
  <TR>
    <TD><tt>can_timeout_handshake</tt></TD>
    <TD>Indicates if the transport supports a timeout when performing the
        initial handshake with the debugger when the connection is established </TD
  </TR>
</TABLE>

<p>This function does not return any errors. </p>


<a name="Universal"></a>
<hr noshade width=75%>
<h3>Universal Errors</h3>

<p>
<TABLE BORDER="0" WIDTH="100%">
  <TR>
    <TD><tt>JDWPTRANSPORT_ERROR_NONE</tt></TD>
    <TD>No error has occurred. This is the error code that is returned on 
        successful completion of the function. </TD>
  </TR>
  <TR>
    <TD><tt>JDWPTRANSPORT_ERROR_OUT_OF_MEMORY</tt></TD>
    <TD>The function needed to allocate memory and no more memory was 
        available for allocation. </TD>
  </TR>
    <TR>
    <TD><tt>JDWPTRANSPORT_ERROR_INTERNAL</tt></TD>
    <TD>An unexpected internal error has occurred.</TD>
  </TR>
</TABLE>

<hr noshade width=75%>


<hr size="3" noshade="noshade">
<table summary="layout" border="0" width="100%">
<tbody>
<tr valign="top">
<td><font size="-2">
<a href="../../relnotes/SMICopyright.html">Copyright</a>© 2004 
<a href="http://www.sun.com/">Sun Microsystems, Inc.</a> All Rights Reserved.</font> 
             
      <p><font size="-1">Please send comments to: <a href="mailto:java-debugger@sun.com">java-debugger@sun.com</a> </font></p>
</td>
<td align="right"><img src="../../images/sunlogo64x30.gif" alt="Sun" border="0" width="64" height="30"></td>
</tr>
</tbody>
</table>





</body>
</html>
