Spec-Zone .ru
спецификации, руководства, описания, API
|
|
Spec-Zone .ru
спецификации, руководства, описания, API
|
Транспорт реализуется как серия функций в динамической библиотеке (иногда названный DLL, или совместно используемой библиотекой). Библиотека экспортирует функцию onload, которая вызывается JDWP (или другой) агент в разовом запуском.
Как JVMTI, jdwpTransport функции получаются доступ через указатель на интерфейс, названный указателем среды. Указатель среды является указателем на среду и имеет тип jdwpTransportEnv*. Указатель среды возвращается к JDWP (или другой) агент от функции onload.
Транспорт может поддерживать единственную среду, или он может поддерживать многократные среды. Другими словами транспорт может использоваться только одним, или многократными агентами одновременно. Если транспорт будет поддерживать многократные среды тогда, то каждый звонок в функцию onload возвратит новый указатель среды. Если транспорт только будет поддерживать единственную среду тогда, то вторые, и последующие звонки в функцию onload возвратят ошибку.
Транспорт ориентирован на многопотоковое исполнение, и функции jdwpTransport могут использоваться многократными параллельными потоками. Например, один поток может быть блокирован в jdwpTransport функции ReadPacket, ожидающей пакета, в то время как другой поток вызывает функцию WritePacket, чтобы записать пакет.
В большинстве случаев функции jdwpTransport возвращают статус возврата указания значения jdwpTransportError. Некоторые функции возвращают дополнительные значения через указатели, обеспеченные функцией вызова. В случаях, где возвращаемые значения выделяются функцией jdwpTransport тогда, функция будет использовать подпрограмму выделения памяти, определенную агентом. Подпрограммы выделения памяти определяются к транспорту, при запуске, через функцию onload.
В случае ошибки (то есть, одна из функций jdwpTransport возвращает значение кроме JDWPTRANSPORT_ERROR_NONE) тогда строка, представляющая ошибку, может быть впоследствии получена посредством звонка в функцию jdwpTransport GetLastError. Ошибки записываются на основе на поток. Функция GetLastError возвратит строку represetning последняя ошибка, с которой встретился текущий поток только.
Транспортная библиотека может быть разработана на любом родном языке, который поддерживает соглашения о вызовах языка C и определения C++ или C.
Функция, тип данных, и постоянные определения, необходимые для того, чтобы использовать интерфейс jdwpTransport, определяются во включать файле jdwpTransport.h. Чтобы использовать эти определения добавляют Java, SE включают каталог в Ваш включать путь:-
#include "jdwpTransport.h"
Транспортная библиотека должна экспортировать функцию onload со следующим прототипом:-
JNIEXPORT jint JNICALL
jdwpTransport_OnLoad(JavaVM *jvm,
jdwpTransportCallback *callback,
jint version,
jdwpTransportEnv** env);
Эта функция будет вызвана JDWP (или другой агент), когда библиотека будет загружена.
Параметром jvm является интерфейс вызова JNI, полученный агентом, вызывая функцию GetJavaVM JNI.
Параметром callback является указатель на функциональную таблицу подпрограмм управления памятью, которые транспорт должен использовать, чтобы выделить память для возвращаемых значений, которые выделяются транспортной реализацией:-
typedef struct jdwpTransportCallback {
void* (*alloc)(jint numBytes);
void (*free)(void *buffer);
} jdwpTransportCallback;
Продолжительность жизни параметра callback является функцией onload, и поэтому транспорт должен сделать копию функциональной таблицы в функции jdwpTransport_OnLoad.
У функциональной таблицы есть две записи. Функция alloc выделяет область памяти. У этого есть единственный параметр, чтобы определить число байтов, чтобы выделить. Это возвращает указатель на begining выделенной памяти, или НУЛЬ, если запрос памяти нельзя соблюдать. Если число байтов, которые требуют, является нулем тогда, НУЛЬ возвращается. Функция free освобождает область памяти, которая была ранее выделена, используя функцию alloc.
Функции управления памятью, обеспеченные агентом, ориентированы на многопотоковое исполнение, и транспортная реализация не обязана синхронизировать звонки в эти функции. Реализация функций управления памятью, как гарантируют, не вызовет любую jdwpTransport функцию.
version является версией транспортного интерфейса, который ожидает агент. Это должно быть определено как JDWPTRANSPORT_VERSION_1_0.
env является указателем на указатель среды, возвращенный функцией.
Функция jdwpTransport_OnLoad возвращает JNI_OK, если транспорт инициализирует успешно. Если инициализация перестала работать тогда, одна из следующих ошибок возвращается:
JNI_ENOMEM JNI_EVERSION JNI_EEXIST
JNI_ENOMEM возвращается, если есть недостаточная память, чтобы завершить инициализацию.
JNI_EVERSION возвращается, если версией в параметре version не является JDWPTRANSPORT_VERSION_1_0.
JNI_EEXIST возвращается, если транспорт только поддерживает единственную среду, и указатель среды был ранее возвращен первым звонком в функцию onload.
Функции jdwpTransport попадают в эти категории:
Функции управления соединением используются, чтобы установить и закрыть соединение с отладчиком. Соединение обеспечивает надежный поток пакетов JDWP к и от отладчика. Пакеты, записанные соединению, читаются, отладчиком, в точно порядке, в котором они были записаны. Точно так же любые пакеты, записанные соединению отладчиком, читаются в порядке, в котором они были записаны.
Соединения устанавливаются или активно или пассивно. Установление соединения активно означает, что функция Attach jdwpTransport вызывается, чтобы инициировать соединение отладчик. Установление соединения пассивно означает, что функция StartListening jdwpTransport используется, чтобы поместить транспорт в, слушают режим так, чтобы это прислушалось к соединению от отладчика. Однажды в слушают режим, функция Accept используется, чтобы принять соединение. Независимо от того, как устанавливается соединение, функция Close используется, чтобы закрыть соединение, и IsOpen используется, чтобы протестировать, если соединение открыто для отладчика.
jdwpTransportError
Attach(jdwpTransportEnv* env, const char* address,
jlong attachTimeout, jlong handshakeTimeout)
Присоединяет к отладчику. Присоединение к отладчику включает два шага. Во-первых, соединение устанавливается к указанному address. Как только соединение устанавливается, квитирование выполняется, чтобы гарантировать, что соединение действительно устанавливается к отладчику. Квитирование включает обмен строковым JDWP-квитированием ASCII как определено в спецификации Протокола Провода Отладки Java.
Параметром address является указатель на строку, представляющую адрес отладчика. Точный формат является определенным для транспорта (В случае TCP/IP базируемый транспорт, адрес может включать имя узла и номер порта отладчика. В случае транспорта, который поддерживает соединения через последовательный порт, это могло бы быть имя устройства последовательного порта).
Параметр attachTimeout определяет тайм-аут, чтобы использовать, присоединяя. Если транспорт поддерживает присоединить тайм-аут (см. GetCapabilities), и если attachTimeout положителен тогда, что это определяет тайм-аут, в миллисекундах (более или менее), чтобы использовать, присоединяя к отладчику. Если транспорт не поддерживает присоединить тайм-аут, или если attachTimeout определяется как нуль тогда, тайм-аут не используется, присоединяя.
Параметр handshakeTimeout определяет тайм-аут, чтобы использовать когда квитирование с отладчиком. Если транспорт поддерживает тайм-аут квитирования (см. GetCapabilities), и если handshakeTimeout положителен тогда, что это определяет тайм-аут, в миллисекундах (более или менее), чтобы использовать когда квитирование с отладчиком. Точное использование тайм-аута квитирования является определенным для транспорта - например, одна реализация может использовать тайм-аут в качестве межсимвольного тайм-аута, ожидая сообщения JDWP-квитирования от отладчика. Другая реализация может использовать тайм-аут, чтобы указать на полную продолжительность, учтенную обмен квитирования. Вообще цель тайм-аута квитирования состоит в том, чтобы учесть обработку ошибок, когда транспорт соединяется с чем-то другим чем допустимый отладчик. Если транспорт не поддерживает тайм-аут квитирования, или если handshakeTimeout определяется как нуль тогда, тайм-аут не используется когда квитирование.
Эта функция возвращает универсальную ошибку или одну из следующих ошибок:
JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT JDWPTRANSPORT_ERROR_ILLEGAL_STATE JDWPTRANSPORT_ERROR_IO_ERROR JDWPTRANSPORT_ERROR_TIMEOUT
JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT возвращается, если address недопустим, или timeout отрицателен.
JDWPTRANSPORT_ERROR_ILLEGAL_STATE возвращается, если транспорт находится в настоящий момент в, слушают режим (см. StartListening), или уже есть открытое соединение с отладчиком (см. IsOpen).
JDWPTRANSPORT_ERROR_IO_ERROR возвращается, если есть ошибка (кроме присоединить тайм-аута) присоединяющий к отладчику. Отметьте, что ошибки во время квитирования запуска (включая тайм-аут квитирования) считают ошибками ввода-вывода. Ошибки ввода-вывода являются определенными для транспорта. GetLastError может использоваться, чтобы получить строковое представление ошибки.
JDWPTRANSPORT_ERROR_TIMEOUT возвращается, если транспорт поддерживает присоединить тайм-аут, и если значение attachTimeout положительно, и если соединение с отладчиком не может быть установлено в пределах этого attachTimeout период.
jdwpTransportError StartListening(jdwpTransportEnv* env, const char* address, char** actualAddress);
Помещает транспорт в, слушают режим, чтобы прислушаться к соединению от отладчика.
Параметром address является указатель на строку, представляющую локальный адрес, на котором должен слушать транспорт. Точный формат является определенным для транспорта (В случае TCP/IP базируемый транспорт, адрес мог бы локальный номер порта TCP. В случае транспорта, который поддерживает соединения через последовательный порт, это могло бы быть имя устройства последовательного порта). Параметр address может быть определен как NULL, или как пустая строка (первым символом является \0). В этом случае транспорт слушает на адресе значения по умолчанию, который является определенным для транспорта.
Если actualAddress не является NULL тогда, это устанавливается в адрес строки, возвращенной функцией StartListening. Возвращенная строка будет содержать строковое представление адреса, на котором слушает транспорт. Это, или не может, может отличаться от адреса, обеспеченного в параметре address. Строка выделяется, используя обратный вызов выделения, обеспеченный для транспорта, когда функция jdwpTransport_OnLoad была вызвана. Вызывающая сторона ответственна за освобождение возвращенной строки.
Эта функция возвращает универсальную ошибку или одну из следующих ошибок:
JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT JDWPTRANSPORT_ERROR_ILLEGAL_STATE JDWPTRANSPORT_ERROR_IO_ERROR
JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT возвращается, если address недопустим.
JDWPTRANSPORT_ERROR_ILLEGAL_STATE возвращается, если уже есть открытое соединение с отладчиком (см. IsOpen), или транспорт уже находится в, слушают режим.
JDWPTRANSPORT_ERROR_IO_ERROR возвращается, если есть ошибка, помещая транспорт в, слушают режим. Природа ошибки является определенной для транспорта. GetLastError может использоваться, чтобы получить строку, представляющую ошибку.
jdwpTransportError StopListening(jdwpTransportEnv* env)
Берет транспорт из, слушают режим так, чтобы это больше не прислушалось к соединениям от отладчика.
Если транспорт находится в, слушают режим тогда, это будет вынуто из этого режима. Если есть открытое (см. IsOpen), соединение с отладчиком тогда это незатронуто этой функцией. Другими словами StopListening не закрывает соединение с отладчиком. Если транспорт не находится в, слушают режим тогда, эта функция ничего не делает, и никакая ошибка не возвращается.
Эта функция возвращает универсальную ошибку или одну из следующих ошибок:
JDWPTRANSPORT_ERROR_IO_ERROR
JDWPTRANSPORT_ERROR_IO_ERROR возвращается, если есть ошибка, беря транспорт из, слушают режим. Природа ошибки является определенной для транспорта. GetLastError может использоваться, чтобы получить строку, представляющую ошибку.
jdwpTransportError Accept(jdwpTransportEnv* env, jlong acceptTimeout, jlong handshakeTimeout)
Принимает соединение от отладчика. Принятие соединения от отладчика включает два шага. Во-первых, соединение устанавливается отладчиком. Как только соединение устанавливается, квитирование выполняется, чтобы гарантировать, что соединение было действительно установлено отладчиком. Квитирование включает обмен строковым JDWP-квитированием ASCII как определено в спецификации Протокола Провода Отладки Java.
Параметр acceptTimeout определяет тайм-аут, чтобы использовать, ожидая отладчика, чтобы соединиться. Если транспорт поддерживает принять тайм-аут (см. GetCapabilities), и если acceptTimeout положителен тогда, что это определяет тайм-аут, в миллисекундах (более или менее), чтобы использовать, ожидая соединения от отладчика. Если транспорт не поддерживает принять тайм-аут, или если timeout определяется, поскольку нуль тогда блокирует неопределенно ожидание соединения.
Параметр handshakeTimeout определяет тайм-аут, чтобы использовать когда квитирование с отладчиком. Если транспорт поддерживает тайм-аут квитирования (см. GetCapabilities), и если handshakeTimeout положителен тогда, что это определяет тайм-аут, в миллисекундах (более или менее), чтобы использовать когда квитирование с отладчиком. Точное использование тайм-аута квитирования является определенным для транспорта - например, одна реализация может использовать тайм-аут в качестве межсимвольного тайм-аута, ожидая сообщения JDWP-квитирования от отладчика. Другая реализация может использовать тайм-аут, чтобы указать на полную продолжительность, учтенную обмен квитирования. Вообще цель тайм-аута квитирования состоит в том, чтобы учесть обработку ошибок, когда что-то другое чем отладчик устанавливает соединение с отлаживаемой программой. Если транспорт не поддерживает тайм-аут квитирования, или если handshakeTimeout определяется как нуль тогда, тайм-аут не используется когда квитирование.
Эта функция возвращает универсальную ошибку или одну из следующих ошибок:
JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT JDWPTRANSPORT_ERROR_ILLEGAL_STATE JDWPTRANSPORT_ERROR_IO_ERROR JDWPTRANSPORT_ERROR_TIMEOUT
JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT возвращается, если attachTimeout или handshakeTimeout отрицательны.
JDWPTRANSPORT_ERROR_ILLEGAL_STATE возвращается, если уже есть открытое соединение с отладчиком (см. IsOpen), или если транспорт не находится в, слушают режим (см. StartListening).
JDWPTRANSPORT_ERROR_IO_ERROR возвращается, если есть ошибка (кроме принять тайм-аута), принимая соединение от отладчика. Отметьте, что ошибки во время квитирования запуска (включая тайм-аут квитирования) считают ошибками ввода-вывода. Природа ошибки является определенной для транспорта. GetLastError может использоваться, чтобы получить строку, представляющую ошибку.
JDWPTRANSPORT_ERROR_TIMEOUT возвращается, если транспорт поддерживает принять тайм-аут, и если значение acceptTimeout положительно, и если соединение с отладчиком не может быть установлено в пределах того периода тайм-аута.
Отметьте: поток, который блокируется в Accept, ожидающем соединения от отладчика, может быть прерван другим потоком, вызывая StopListening. В этом случае поток, который названный Accept возвратит JDWPTRANSPORT_ERROR_IO_ERROR, указывающий на ошибку ввода-вывода, произошел. Если поток, блокированный в Accept, принял соединение и находится в процессе квитирования с отладчиком тогда, StopListening не будет прерывать соединение.
jboolean isOpen(jdwpTransportEnv* env)
Говорит, есть ли соединение, открытое для отладчика.
JNI_TRUE возвратов, если, и только если, есть открытое соединение с отладчиком. Иначе это возвращает JNI_FALSE.
jdwpTransportError Close(jdwpTransportEnv* env)
Закрывает открытое соединение с отладчиком.
Если нет открытого соединения с отладчиком (см. IsOpen), тогда эта функция ничего не делает, и никакая ошибка не возвращается.
Если будут потоки, блокированные в каких-либо функциях ввода-вывода (а именно, ReadPacket и WritePacket), то эти функции ввода-вывода будут прерваны завершением и возвратят JDWPTRANSPORT_ERROR_IO_ERROR, указывающий, что ошибка ввода-вывода произошла.
Эта функция возвращает универсальную ошибку или одну из следующих ошибок:
JDWPTRANSPORT_ERROR_IO_ERROR
JDWPTRANSPORT_ERROR_IO_ERROR возвращается, если есть ошибка, закрывая соединение. Природа ошибки является определенной для транспорта. GetLastError может использоваться, чтобы получить строку, представляющую ошибку.
Функции ввода-вывода используются для чтения и записи пакетов JDWP от и до отладчика.
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)
Читает пакет JDWP от открытого соединения до отладчика.
Эта функция делает чтение блокирования на открытом соединении. Это блокирует неопределенно, пока полный пакет JDWP не может быть возвращен, или в случае транспорта, основанного на потоковом протоколе, с концом потока встречаются.
Параметром packet является адрес структуры jdwpPacket, которая заполняется этой функцией. Поле packet.type.cmd.len ИЛИ packet.type.reply.len (в зависимости от того, если пакет является пакетом команды или ответа) заполняется с длиной пакета. Если с концом потока встретятся, то поле длины будет установлено в 0, и все другие поля в пакете будут неопределены. Если с концом потока встречаются после чтения некоторых, но не всех, байтов пакета, это считают ошибкой ввода-вывода, и JDWPTRANSPORT_ERROR_IO_ERROR будет возвращен. В этом случае поле длины не будет заполнено. Когда весь пакет читается тогда, все поля в пакете заполняются со значениями в порядке узла. Это, или не может, может отличаться от порядка с обратным порядком байтов, требуют, передавая пакеты JDWP.
Поле packet.type.cmd.data ИЛИ packet.type.reply.data (в зависимости от того, если пакет является пакетом команды или ответа) будет заполнено с NULL или указателем на пакетные данные, выделенные этой функцией. Пакетные данные выделяются, используя обратный вызов выделения, обеспеченный для транспорта, когда функция jdwpTransport_OnLoad была вызвана. Вызывающая сторона ответственна, чтобы освободить это. Расположение пакетных данных (который является данными после заголовка, если кто-либо) возвращается к вызывающей стороне в порядке байтов, в котором это было получено.
Функция ReadPacket не делает никакой целостности, проверяющей возвращенный пакет кроме проверки, что длиной пакета (как обозначено на первые 4 байта) является >= 11 байтов. Если поле length составляет меньше чем 11 байтов тогда, JDWPTRANSPORT_ERROR_IO_ERROR возвращается.
Эта функция возвращает универсальную ошибку или одну из следующих ошибок:
JDWPTRANSPORT_ERROR_IO_ERROR JDWPTRANSPORT_ERROR_ILLEGAL_STATE JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT
JDWPTRANSPORT_ERROR_IO_ERROR возвращается, если ошибка ввода-вывода происходит, читая, соединение закрывается асинхронно другим потоком, вызывающим Близкую функцию, или ужасно сформированный пакет (поле length меньше чем 11 байтов) получается. Ошибки ввода-вывода являются определенными для транспорта. GetLastError может использоваться, чтобы получить строку, представляющую ошибку.
JDWPTRANSPORT_ERROR_ILLEGAL_STATE возвращается, если нет открытого соединения с отладчиком (см. IsOpen).
JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT возвращается, если packet является NULL
jdwpTransportError WritePacket(jdwpTransportEnv* env, const jdwpPacket* packet)
Пишет пакет JDWP в открытое соединение.
Параметром packet является указатель на структуру jdwpPacket. Все поля в пакетном заголовке должны быть сохранены в порядке узла. Пакетным полем данных (packet.type.cmd.data или packet.type.reply.data) должен быть NULL, или указатель на расположение, содержащее пакетные данные, которые сразу следуют за заголовком. Пакетные данные, должен быть в сетевом порядке (обратный порядок байтов), готовый к передаче.
Эта функция возвращает универсальную ошибку или одну из следующих ошибок:
JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT JDWPTRANSPORT_ERROR_IO_ERROR JDWPTRANSPORT_ERROR_ILLEGAL_STATE
JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT, если packet является NULL, или если пакетное поле длины (packet.type.cmd.len или packet.type.reply.len) является меньше чем 11, или это больше чем 11, но пакетным полем данных (packet.type.cmd.data или packet.type.reply.data) является NULL.
JDWPTRANSPORT_ERROR_IO_ERROR возвращается, если ошибка ввода-вывода происходит при записи, или соединение закрывается асинхронно другим потоком, вызывающим Близкую функцию. Ошибки ввода-вывода являются определенными для транспорта. GetLastError может использоваться, чтобы получить строку, представляющую ошибку.
JDWPTRANSPORT_ERROR_ILLEGAL_STATE возвращается, если нет открытого соединения с отладчиком (см. IsOpen).
jdwpTransportError GetLastError(jdwpTransportEnv* env, char** msg);
Возвращает строковое представление последней ошибки.
Когда ошибка происходит, она записывается на основе на поток. Последующий звонок в GetLastError возвращает строковое представление последней ошибки ввода-вывода.
Параметром msg является указатель на завершенную нулем строку, возвращенную этой функцией. Строка выделяется, используя обратный вызов выделения, обеспеченный для транспорта, когда функция jdwpTransport_OnLoad была вызвана. Вызывающая сторона ответственна, чтобы освободить возвращенную строку.
Эта функция возвращает универсальную ошибку или одну из следующих ошибок:
JDWPTRANSPORT_ERROR_MSG_NOT_AVAILABLE
JDWPTRANSPORT_ERROR_MSG_NOT_AVAILABLE возвращается, если этот поток не встретился с ошибкой ввода-вывода или нет строкового представления последней доступной ошибки.
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)
Возвраты через capabilitiesPtr дополнительные jdwpTransport функции поддерживаются этим транспортом. Структура возможностей содержит много булевых флагов, указывающих, поддерживается ли именованная функция. Текущий набор флагов:
| Булев Флаг | Значение |
|---|---|
| can_timeout_attach | Указывает, поддерживает ли транспорт присоединение с тайм-аутом |
| can_timeout_accept | Указывает, поддерживает ли транспорт принять тайм-аут |
| can_timeout_handshake | Указывает, поддерживает ли транспорт тайм-аут, выполняя начальное квитирование с отладчиком, когда соединение устанавливается |
Эта функция не возвращает ошибок.
| Ошибка | Значение |
|---|---|
| JDWPTRANSPORT_ERROR_NONE | Никакая ошибка не произошла. Это - код ошибки, который возвращается на успешном завершении функции. |
| JDWPTRANSPORT_ERROR_OUT_OF_MEMORY | Функция должна была выделить память, и больше памяти не было доступно для выделения. |
| JDWPTRANSPORT_ERROR_INTERNAL | Произошла неожиданная внутренняя ошибка. |
