Средства разработки приложений
         

Описание протокола DDE


Начнем с краткого описания протокола DDE. Материал статьи охватывает только ту часть API протокола, которая необходима для организации «горячего» канала DDE.

Протокол DDE подразумевает клиент-серверную архитектуру. Это значит, что одно их приложений выступает в качестве сервера, а второе – клиента. В нашем случае сервером выступает приложение MS Excel, а приложения .NET являются для него клиентами. Обмен данными между приложениями происходит посредством транзакций. Управляет всем процессом специальное расширение ОС Windows - динамическая библиотека DDEML.

По протоколу DDE, сервер в первую очередь должен зарегистрировать себя в библиотеке DDEML. После этого он регистрирует предоставляемые сервисы.

Клиентское приложение также сначала регистрирует себя в библиотеке DDEML. После этого клиентское приложение создает канал связи с сервером.

Протокол DDE поддерживает три вида обмена данными между клиентом и сервером:

  • По явному запросу
  • «Теплый канал»
  • «Горячий канал»

В первом случае клиент явным образом посылает серверу запрос, указывая нужный элемент данных. Сервер, получив подобный запрос, предоставляет клиенту эти данные.

В случае организации «теплого канала» сервер, при изменении данных, отправляет клиенту извещение. Клиент, получив это извещение, может послать запрос серверу на получение этих данных, после чего сервер предоставляет данные клиенту.

В случае «горячего канала» сервер будет отправлять клиенту данные, не ожидая явного запроса при их изменении.

На практике, как правило, используется либо передача данных по явному запросу, либо «горячий канал», причем второй очень удобен при организации быстрого обмена данными между приложениями в режиме реального времени. Именно «горячий» канал и будет рассматриваться в этой статье.

В библиотеке DDEML данные адресуются трехступенчатой схемой: сервис (service), раздел (topiс) и элемент данных (data item). Для сервера DDE приложения MS Excel, эта схема выглядит следующим образом:

  • Зарегистрированный сервис (service): “EXCEL”
  • Разделы данных (topics): “[название_книги]название_страницы”, например “[Книга1]Лист1”.
  • Элемент данных(item) – описание ячейки: “Rномер_строкиСномер_столбца”, например “R1C2” адресует ячейку в первой строке и во втором столбце.
    При этом нумерация строк в MS Excel начинается с единицы.
Для установления связи, приложение должно сначала зарегистрировать себя в библиотеке DDEML и получить свой программный идентификатор. Этот идентификатор необходимо хранить в течение всей работы, так как для каждого приложения, которое регистрируется в библиотеке DDEML, создается своя копия необходимых структур данных.
Регистрация в библиотеке DDEML происходит с помощью функции DdeInitialize, которая имеет следующую сигнатуру:
UINT WINAPI DdeInitialize(
DWORD FAR* pidInst,
PFNCALLBACK pfnCallback,
DWORD afCmd,
DWORD ulRes);
Параметры, которые передаются функции при вызове:
  • pidInst – ссылка на переменную типа «двойное слово», в которую функция запишет программный идентификатор, присваиваемый приложения библиотекой DDEML. Перед вызовом функции программа должна обнулить значение этой переменной.
  • pfnCallback – указатель на функцию обратного вызова.
  • afCmd – набор битовых флагов инициализации, а также устанавливающий некоторые специфические условия работы с библиотекой.
  • ulRes – зарезервировано и должно быть равно нулю.
В случае успешной регистрации, функция DdeInitialize возвращает нулевое значение. Если при инициализации произошла ошибка, то функция вернет код ошибки.
Если приложение больше не собирается работать с библиотекой DDEML, то оно должно вызвать функцию DdeUninitialize, передав ей в качестве параметра программный идентификатор, полученный при регистрации:
BOOL WINAPI DdeUninitialize(DWORD idInst);
После успешной инициализации, клиентское приложение должно создать канал связи с сервером. Для каждого сервиса и раздела создается свой канал связи. После успешного создания канала, ему присваивается идентификатор, который указывается в дальнейших транзакциях, как клиентом, так и сервером.
Адресация происходит посредством строк, однако в транзакциях используются их идентификаторы. Эти идентификаторы присваиваются каждой строке библиотекой DDEML и хранятся в специальной системной таблице идентификации строк.


Для создания идентификатора строки, необходимо воспользоваться функцией DdeCreateStringHandle:
HSZ WINAPI DdeCreateStringHandle(
DWORD idInst,
LPCSTR psz,
Int iCodePage);
Функция получает следующие параметры:
  • idInst – программный идентификатор приложения, полученный при регистрации в библиотеке DDEML;
  • psz – адрес текстовой строки, завершенной двоичным нулем. Длина строки не должна превышать 255 байт.
  • iCodePage – кодовая страница, определяющая тип строки, получаемой на вход. При указании константы CP_WINANSI данная строка рассматривается как строка ANSI. Если указать константу CP_WINUNICODE, то строка рассматривается как состоящая из символов Unicode.
Функция возвращает идентификатор, который библиотека DDEML присвоила данной строке.
Для того, чтобы освободить ресурсы, связанные с зарегистрированной строкой, клиентское приложение должно вызвать функцию отмены регистрации данной строки DdeFreeStringHandle:
BOOL WINAPI DdeFreeStringHandle(
DWORD idInst,
HSZ hsz);
В качестве параметров функция получает следующее:
  • idInst – программный идентификатор приложения, полученный при регистрации в библиотеке DDEML;
  • hsz – идентификатор строки.
Функция возвращает значение true, если операция прошла успешно, и false - если при выполнении функции произошли ошибки.
Для того, чтобы получить строку по ее идентификатору, необходимо воспользоваться функцией DdeQueryString:
DWORD WINAPI DdeQueryString(
DWORD idInst,
HSZ hsz,
LPSTR psz,
DWORD cchMax,
Int iCodePage
);
В качестве параметров функция получает следующее:
  • idInst - программный идентификатор приложения, полученный при регистрации в библиотеке DDEML;
  • hsz – идентификатор строки, которую нужно получить.
  • psz – указательна буфер, в который будет записана строка
  • cchMax – максимальная длина строки в символах. Вид символа определяется следующим по порядку параметром и может быть ANSI (1 байт) или Unicode (2 байта)
  • iCodePage – определяет тип символов строки. Возможные значения CP_WINANSI – для символов стандарта ANSI (1 байт) и CP_WINUNICODE – для символов стандарта Unicode (2 байта).
Функция возвращает количество скопированных символов.


При  этом если фактическая длина строки (в символах) меньше указанной в параметре cchMax, то функция скопирует cchMax символов и вернет это значение. Если cchMax больше фактической длины строки, то функция скопирует всю строку и вернет количество скопированных символов. Если передать через параметр   psz нулевое значение, то функция проигнорирует значение параметра cchMax и вернет фактическую длину строки в символах. Размер буфера в байтах для строки зависит от размера символа и определяется параметром iCodePage.
Для получения данных из глобальной области памяти по их идентификатору нужно воспользоваться функцией DdeGetData:
DWORD WINAPI DdeGetData(
HDDEDATA hData,
void FAR* pDst,
DWORD cbMax,
DWORD cbOff
);
Функция должна получить на вход следующие параметры:
  • hData -  идентификатор порции данных в глобальной области памяти;
  • pDst – указатель на буфер, куда будут скопированы данные из глобальной области.
  • cbMax – размер буфера в байтах. Если фактический размер данных больше размера области в буфере, которая выделяется под эти данные(см. ниже параметр cbOff), то будут скопированы только первые (cbMax – cbOff) байт. Иначе функция скопирует все данные в буфер.
  • cbOff – смещение в буфере относительно начала, с которого функция поместит в буфер данные из глобальной области.
Функция возвратит количество фактически скопированных байт данных. Если вместо ссылки на буфер через параметр pDst передать нулевое значение, то функция вернет фактический размер порции данных в глобальной области памяти, при этом значение параметров cbMax и cbOff будут проигнорированы.
Канал связи DDE создается с помощью функции DdeConnect:
HCONV WINAPI DdeConnect(
DWORD idInst,
HSZ hszService,
HSZ hszTopic,
CONVCONTEXT FAR* pCC);
В качестве параметров функция должна получить следующее:
  • idInst - программный идентификатор приложения, полученный при регистрации в библиотеке DDEML;
  • hszService – идентификатор строки названия сервиса, который необходимо предварительно получить вызовом функции DdeCreateStringHandle
  • hszTopic – идентификатор строки названия раздела, который также заранее запрашивается у библиотеки DDEML вызовом функции DdeCreateStringHandle;
  • pCC – указатель на специальную структуру типа CONVCONTEXT, в которой указывается информация о национальном языке и кодовой странице.


    В большинстве случаев ( в нашем тоже) достаточно указать нулевое значение, что означает использование кодовой страницы ANSI.
Функция возвращает идентификатор созданного канала связи. В случае ошибки функция вернет нулевое значение. Полученный идентификатор канала необходимо хранить в течение всего сеанса связи.
Когда приложение завершает работу с каналом, оно должно закрыть его, вызвав функцию DdeDisconnect:
BOOL WINAPI DdeDisconnect(HCONV hConv);
В качестве параметра функция получает идентификатор канала, который нужно закрыть. Функция возвращает true, если канал успешно закрыт и false в случая возникновения ошибок при закрытии канала.
После того, как был создан канал связи, можно начинать обмен данными. Обмен происходит посредством транзакций с помощью функции DdeClientTransaction и функции обратного вызова DdeCallbackFunction. Если приложение (независимо от того, клиент или сервер) хочет отправить данные, то оно должно подготовить их, оформить контекст с помощью функций библиотеки DDEML , а потом вызвать функцию DdeClientTransaction. При этом принимающему приложению будет отправлено сообщение, которое осуществит вызов функцию обратного вызова принимающей стороны. Функции обратного вызова представляют особой обработчик с множественным ветвлением, каждая ветвь которого обрабатывает соответствующую ей транзакцию. Если транзакция не поддерживается, то функция обратного вызова должна вернуть нулевое значение, иначе – один из допустимых для обработанной транзакции, кодов возврата.
Функция обратного вызова имеет следующий заголовок:
HDDEDATA EXPENTRY  DdeCallbackFunction(
WORD wType,
WORD wFmt,
HCONV hConv,
HSZ hsz1,
HSZ hsz2,
HDDEDATA hData,
DWORD dwData1,
DWORD dwData2
);
где:
  • wType -  Код транзакции. Коды транзакций предопределены протоколом DDE. Значения и названия соответствующих им констант можно посмотреть в технической документации. Забегая вперед, отмечу, что в нашем примере будут использоваться транзакции XTYP_ADVSTART для запуска потока данных по каналу, XTYP_ADVSTOP – для остановки потока данных, XTYP_ADVDATA – транзакция с уведомлением наличии данных от сервера.
  • wFmt – формат данных (в нашем случае данные представляют собой текстовую строку, поэтому этому параметру при вызове будет присвоено значение CF_TEXT, равное единице).
  • hConv – идентификатор канала.


    Этот идентификатор получен при создании канала.
  • hsz1 – идентификатор строки названия раздела.
  • hsz2 – идентификатор строки названия элемента данных.
  • hData – идентификатор глобальной области в памяти, где находятся данные от сервера. Данные необходимо получить с помощью функции DdeGetData.
В свою очередь функция запуска транзакции DdeClientTransaction имеет следующий заголовок:
HDDEDATA WINAPI DdeClientTransaction(
void FAR* pData,
DWORD cbData,
HCONV hConv,
HSZ hszItem,
UINT uFmt,
UINT uType,
DWORD dwTimeout,
DWORD FAR* pdwResult
);
  • pData - ссылка на данные, передаваемые транзакцией.
  • cbData - размер передаваемых данных
  • hConv - идентификатор канала связи, полученный заранее функцией DdeConnect
  • hszItem - идентификатор элемента данных, в нашем случае - ячейки. Идентификатор должен быть получен заранее, с помощью функции DdeCreateStringHandle.
  • uFmt - формат данных. Для случая с Excel указывается константа CF_TEXT(1)
  • uType - код транзакции. Определяется комбинацией битовых флагов. В случае организации горячего канала выполняется транзакция XTYP_ADVSTART - для начала цикла получения данных из ячейки (подписки на ячейку) и XTYP_ADVSTOP - для прекращения цикла получения данных из ячейки (отписки от ячейки).
  • dwTimeout - тайм-аут для синхронных транзакций - максимальное время выполнения синхронной транзакции. Если в качестве параметра передать 0, то будет запущена асинхронная транзакция. При запуске синхронной транзакции, приложение ждет ее завершения. При этом максимальное время выполнения транзакции определяется значением параметра. При запуске асинхронной транзакции приложение не ждет завершения транзакции и продолжает свою работу. По завершению транзакции клиент получит транзакцию XTYP_XACT_COMPLETE.
  • pdwResult - ссылка на двойное слово, в которое будет записан код завершения транзакции. Изначально эта переменная должна быть приравнена к нулю. (По рекомендации Microsoft, не рекомендуется использовать этот параметр, так как, возможно, в дальнейшем он поддерживаться не будет).
  • Возвращает нулевое значение, если транзакция была выполнена с ошибкой, или ненулевую величину, смысл которой зависит от транзакции, (В нашем случае будет возвращена единица) при нормальном выполнении.


Содержание раздела