IWDFRemoteInterfaceInitialize::RetrieveSymbolicLink-Methode (wudfddi.h)

Artikel
02/07/2025

[Warnung: UMDF 2 ist die neueste Version von UMDF und ersetzt UMDF 1. Alle neuen UMDF-Treiber sollten mit UMDF 2 geschrieben werden. Es werden keine neuen Features zu UMDF 1 hinzugefügt, und es gibt eingeschränkte Unterstützung für UMDF 1 für neuere Versionen von Windows 10. Universelle Windows-Treiber müssen UMDF 2 verwenden. Weitere Informationen finden Sie unter Erste Schritte mit UMDF-.]

Die RetrieveSymbolicLink--Methode ruft den symbolischen Verknüpfungsnamen ab, den das Betriebssystem einer Geräteschnittstellezugewiesen hat.

Syntax

HRESULT RetrieveSymbolicLink(
  [out, optional] PWSTR pSymbolicLink,
  [in, out]       DWORD *pdwSymbolicLinkLengthInChars
);

Parameter

[out, optional] pSymbolicLink

Ein Zeiger auf einen Puffer, der eine null-terminated Unicode-Zeichenzeichenfolge empfängt, die den symbolischen Verknüpfungsnamen darstellt. Legen Sie diesen Zeiger auf NULL- fest, um die erforderliche Puffergröße abzurufen.

[in, out] pdwSymbolicLinkLengthInChars

Ein Zeiger auf einen vom Anrufer zugewiesenen Standort. Bei eingaben muss dieser Speicherort die vom Aufrufer bereitgestellte Länge des Puffers enthalten, auf den pSymbolicLink verweist. Bei der Ausgabe empfängt die Position die Länge des symbolischen Verknüpfungsnamens in Zeichen, einschließlich des NULL-zeichens Endzeichen.

Rückgabewert

RetrieveSymbolicLink- gibt S_OK zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt die Methode möglicherweise den folgenden Wert zurück:

Rückgabecode	Beschreibung
E_NOT_SUFFICIENT_BUFFER	Der Puffer, auf den pSymbolicLink verweist, ist zu klein. In diesem Fall speichert das Framework die erforderliche Puffergröße an der Position, auf die pdwSymbolicLinkLengthInChars verweist.

Diese Methode gibt möglicherweise einen der anderen Werte zurück, die Winerror.h enthält.

Bemerkungen

Der name der symbolischen Verknüpfung kann ein angefügtes umgekehrtes Schrägstrichzeichen () gefolgt von einer instanzspezifischen Verweiszeichenfolge enthalten.

Normalerweise sollte Ihr Treiber RetrieveSymbolicLink- zweimal aufrufen, wie folgt:

Legen Sie den parameter pSymbolicLink auf NULL- fest, und rufen Sie RetrieveSymbolicLink-auf. Die Position, die pdwSymbolicLinkLengthInChars verweist, um die Anzahl der Zeichen zu erhalten, die der symbolische Verknüpfungsname enthält.
Weisen Sie einen Puffer zu, der groß genug ist, um den symbolischen Linknamen zu erhalten.
Rufen Sie RetrieveSymbolicLink erneut auf, und legen Sie den pSymbolicLink Parameter auf die Adresse des zugeordneten Puffers fest.

Weitere Informationen zur RetrieveSymbolicLink--Methode finden Sie unter Verwenden von Geräteschnittstellen in UMDF-basierten Treibern.

Beispiele

Im folgenden Codebeispiel wird gezeigt, wie die IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival Rückruffunktion die Länge des symbolischen Verknüpfungsnamens der Geräteschnittstelle bestimmen, einen Puffer für den Namen zuordnen und dann den Namen abrufen kann.

void 
STDMETHODCALLTYPE
CMyDevice::OnRemoteInterfaceArrival(
    __in IWDFRemoteInterfaceInitialize  *FxRemoteInterfaceInit
    )
{
    HRESULT hr;
    INT BufferSize;
    hr= FxRemoteInterfaceInit->RetrieveSymbolicLink(NULL,
                                                    &BufferSize);
    if (FAILED(hr)) goto Error;
    hr = FxDriver->CreateWdfMemory(BufferSize, 
                                   NULL, 
                                   FxRemoteInterface, 
                                   &FxSymLinkBuffer);
    if (FAILED(hr)) goto Error;
    hr= FxRemoteInterfaceInit->RetrieveSymbolicLink(FxSymLinkBuffer->GetDataBuffer(NULL),
                                                    &BufferSize);
    if (FAILED(hr)) goto Error;
...
Error:
...
}

Anforderungen

Anforderung	Wert
Ende des Supports	In UMDF 2.0 und höher nicht verfügbar.
Zielplattform-	Desktop
Mindest-UMDF-Version	1.9
Header-	wudfddi.h (include Wudfddi.h)
DLL-	WUDFx.dll

Siehe auch

IWDFRemoteInterfaceInitialize

IWDFRemoteInterfaceInitialize::GetInterfaceGuid

Freigeben über