DdeCreateStringHandleA-Funktion (ddeml.h)

Artikel
11/20/2024

Erstellt ein Handle, das die angegebene Zeichenfolge identifiziert. Ein DDE-Client (Dynamic Data Exchange) oder eine Serveranwendung kann das Zeichenfolgenhandle als Parameter an andere DDEML-Funktionen (Dynamic Data Exchange Management Library) übergeben.

Syntax

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

Parameter

[in] idInst

Typ: DWORD-

Der Anwendungsinstanzbezeichner, der durch einen vorherigen Aufruf der DdeInitialize-Funktion abgerufen wurde.

[in] psz

Typ: LPTSTR-

Die mit Null beendete Zeichenfolge, für die ein Handle erstellt werden soll. Diese Zeichenfolge kann bis zu 255 Zeichen lang sein. Der Grund für diesen Grenzwert ist, dass DDEML-Zeichenfolgenverwaltungsfunktionen mithilfe von Atomen implementiert werden.

[in] iCodePage

Typ: int

Die Codeseite, die zum Rendern der Zeichenfolge verwendet werden soll. Dieser Wert sollte entweder CP_WINANSI (standardcodepage) oder CP_WINUNICODE sein, je nachdem, ob die ANSI- oder Unicode-Version von DdeInitialize von der Clientanwendung aufgerufen wurde.

Rückgabewert

Typ: HSZ-

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Zeichenfolgenhandle.

Wenn die Funktion fehlschlägt, lautet der Rückgabewert 0L.

Die funktion DdeGetLastError kann verwendet werden, um den Fehlercode abzurufen, der einen der folgenden Werte sein kann:

Bemerkungen

Der Wert eines Zeichenfolgenhandles bezieht sich nicht auf den Fall der identifizierten Zeichenfolge.

Wenn eine Anwendung entweder ein Zeichenfolgenhandle erstellt oder einen in der Rückruffunktion empfängt und dann die DdeKeepStringHandle--Funktion verwendet, um sie beizubehalten, muss die Anwendung dieses Zeichenfolgenhandle freigeben, wenn sie nicht mehr benötigt wird.

Ein instanzspezifisches Zeichenfolgenhandle kann nicht von Zeichenfolgenhandle zu Zeichenfolge und zurück zum Zeichenfolgenhandle zugeordnet werden. Dies wird im folgenden Beispiel gezeigt, in dem die funktion DdeQueryString eine Zeichenfolge aus einem Zeichenfolgenhandle erstellt und DdeCreateStringHandle ein Zeichenfolgenhandle aus dieser Zeichenfolge erstellt, die beiden Handles sind jedoch nicht identisch:

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

Anmerkung

Der ddeml.h-Header definiert DdeCreateStringHandle als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows 2000 Professional [nur Desktop-Apps]
mindestens unterstützte Server-	Windows 2000 Server [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	ddeml.h (enthalten Windows.h)
Library	User32.lib
DLL-	User32.dll