Funzione DdeCreateStringHandleA (ddeml.h)

Articolo
11/20/2024

Crea un handle che identifica la stringa specificata. Un'applicazione client o server DDE (Dynamic Data Exchange) può passare l'handle di stringa come parametro ad altre funzioni DDEML (Dynamic Data Exchange Management Library).

Sintassi

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

Parametri

[in] idInst

Tipo: DWORD

Identificatore dell'istanza dell'applicazione ottenuto da una chiamata precedente alla funzione DdeInitialize.

[in] psz

Tipo: LPTSTR

Stringa con terminazione Null per cui creare un handle. Questa stringa può contenere fino a 255 caratteri. Il motivo di questo limite è che le funzioni di gestione delle stringhe DDEML vengono implementate usando gli atom.

[in] iCodePage

Tipo: int

Tabella codici da utilizzare per eseguire il rendering della stringa. Questo valore deve essere CP_WINANSI (tabella codici predefinita) o CP_WINUNICODE, a seconda che la versione ANSI o Unicode di DdeInitialize sia stata chiamata dall'applicazione client.

Valore restituito

Tipo: HSZ

Se la funzione ha esito positivo, il valore restituito è un handle stringa.

Se la funzione ha esito negativo, il valore restituito è 0L.

La funzione DdeGetLastError può essere usata per ottenere il codice di errore, che può essere uno dei valori seguenti:

Osservazioni

Il valore di un handle di stringa non è correlato al caso della stringa identificata.

Quando un'applicazione crea un handle stringa o ne riceve uno nella funzione di callback e quindi usa la funzione DdeKeepStringHandle per mantenerla, l'applicazione deve liberare tale handle di stringa quando non è più necessario.

Non è possibile eseguire il mapping di un handle di stringa specifico dell'istanza dall'handle di stringa alla stringa e tornare all'handle di stringa. Questo è illustrato nell'esempio seguente, in cui la funzione DdeQueryString crea una stringa da un handle stringa e DdeCreateStringHandle crea un handle stringa da tale stringa, ma i due handle non sono uguali:

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

Nota

L'intestazione ddeml.h definisce DdeCreateStringHandle come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 2000 Professional [solo app desktop]
server minimo supportato	Windows 2000 Server [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	ddeml.h (include Windows.h)
libreria	User32.lib
dll	User32.dll