Функция DdeCreateStringHandleA (ddeml.h)

Статья
11/20/2024

Создает дескриптор, определяющий указанную строку. Клиент динамического обмена данными (DDE) или серверное приложение может передавать дескриптор строки в качестве параметра другим функциям библиотеки управления динамическими данными (DDEML).

Синтаксис

HSZ DdeCreateStringHandleA(
  [in] DWORD  idInst,
  [in] LPCSTR psz,
  [in] int    iCodePage
);

Параметры

[in] idInst

Тип: DWORD

Идентификатор экземпляра приложения, полученный предыдущим вызовом функции DdeInitialize.

[in] psz

Тип: LPTSTR

Строка, завершающаяся значением NULL, для которой создается дескриптор. Эта строка может составлять до 255 символов. Причина этого ограничения заключается в том, что функции управления строками DDEML реализуются с помощью атомов.

[in] iCodePage

Тип: int

Кодовая страница, используемая для отрисовки строки. Это значение должно быть либо CP_WINANSI (кодовая страница по умолчанию), либо CP_WINUNICODE в зависимости от того, была ли версия ANSI или Юникод DdeInitialize вызвана клиентским приложением.

Возвращаемое значение

Тип: HSZ

Если функция выполнена успешно, возвращаемое значение является строковым дескриптором.

Если функция завершается ошибкой, возвращаемое значение равно 0L.

Функцию DdeGetLastError можно использовать для получения кода ошибки, который может быть одним из следующих значений:

Замечания

Значение дескриптора строки не связано с регистром строки, которая она идентифицирует.

Если приложение создает строковый дескриптор или получает его в функции обратного вызова, а затем использует функцию DdeKeepStringHandle для сохранения, приложение должно освободить этот дескриптор строки, если он больше не нужен.

Дескриптор строки для конкретного экземпляра нельзя сопоставить со строковым дескриптором с строковым дескриптором и обратно с дескриптором строки. Это показано в следующем примере, в котором функция DdeQueryString создает строку из дескриптора строки и DdeCreateStringHandle создает строковый дескриптор из этой строки, но два дескриптора не совпадают:

DWORD idInst; 
DWORD cb; 
HSZ hszInst, hszNew; 
PSZ pszInst; 
 
DdeQueryString(idInst, hszInst, pszInst, cb, CP_WINANSI); 
hszNew = DdeCreateStringHandle(idInst, pszInst, CP_WINANSI); 
// hszNew != hszInst !

Заметка

Заголовок ddeml.h определяет DdeCreateStringHandle как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	ddeml.h (include Windows.h)
библиотеки	User32.lib
DLL	User32.dll