Função DdeCreateStringHandleA (ddeml.h)

Artigo
03/13/2024

Cria um identificador que identifica a cadeia de caracteres especificada. Um aplicativo de servidor ou cliente DDE (Dynamic Data Exchange) pode passar o identificador de cadeia de caracteres como um parâmetro para outras funções DDEML (Dynamic Data Exchange Management Library).

Sintaxe

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

Parâmetros

[in] idInst

Tipo: DWORD

O identificador de instância do aplicativo obtido por uma chamada anterior para a função DdeInitialize .

[in] psz

Tipo: LPTSTR

A cadeia de caracteres terminada em nulo para a qual um identificador deve ser criado. Essa cadeia de caracteres pode ter até 255 caracteres. O motivo para esse limite é que as funções de gerenciamento de cadeia de caracteres DDEML são implementadas usando átomos.

[in] iCodePage

Tipo: int

A página de código a ser usada para renderizar a cadeia de caracteres. Esse valor deve ser CP_WINANSI (a página de código padrão) ou CP_WINUNICODE, dependendo se a versão ANSI ou Unicode de DdeInitialize foi chamada pelo aplicativo cliente.

Retornar valor

Tipo: HSZ

Se a função for bem-sucedida, o valor retornado será um identificador de cadeia de caracteres.

Se a função falhar, o valor retornado será 0L.

A função DdeGetLastError pode ser usada para obter o código de erro, que pode ser um dos seguintes valores:

Comentários

O valor de um identificador de cadeia de caracteres não está relacionado ao caso da cadeia de caracteres que ele identifica.

Quando um aplicativo cria um identificador de cadeia de caracteres ou recebe um na função de retorno de chamada e usa a função DdeKeepStringHandle para mantê-lo, o aplicativo deve liberar esse identificador de cadeia de caracteres quando ele não for mais necessário.

Um identificador de cadeia de caracteres específico da instância não pode ser mapeado do identificador de cadeia de caracteres para a cadeia de caracteres e de volta para o identificador de cadeia de caracteres. Isso é mostrado no exemplo a seguir, no qual a função DdeQueryString cria uma cadeia de caracteres de um identificador de cadeia de caracteres e DdeCreateStringHandle cria um identificador de cadeia de caracteres dessa cadeia de caracteres, mas os dois identificadores não são os mesmos:

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

Observação

O cabeçalho ddeml.h define DdeCreateStringHandle como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	ddeml.h (inclua Windows.h)
Biblioteca	User32.lib
DLL	User32.dll