IWDFRemoteInterfaceInitialize::RetrieveSymbolicLink-Methode (wudfddi.h)

Artikel
02/27/2024

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

Die RetrieveSymbolicLink-Methode ruft den symbolischen Linknamen ab, den das Betriebssystem einer Geräteschnittstelle zugewiesen hat.

Syntax

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

Parameter

[out, optional] pSymbolicLink

Ein Zeiger auf einen Puffer, der eine Unicode-Zeichenfolge mit Null-Beendigung empfängt, die den namen der symbolischen Verknüpfung darstellt. Legen Sie diesen Zeiger auf NULL fest, um die erforderliche Puffergröße abzurufen.

[in, out] pdwSymbolicLinkLengthInChars

Ein Zeiger auf einen vom Aufrufer zugewiesenen Speicherort. Bei der Eingabe muss dieser Speicherort die vom Aufrufer angegebene Länge des Puffers enthalten, auf den pSymbolicLink verweist. Bei der Ausgabe empfängt der Speicherort die Länge des symbolischen Linknamens in Zeichen, einschließlich des NULL-Endzeichens.

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.

Hinweise

Der symbolische Linkname kann einen angefügten umgekehrten Schrägstrich () enthalten, gefolgt von einer instance spezifischen Verweiszeichenfolge.

In der Regel sollte Ihr Treiber RetrieveSymbolicLink wie folgt zweimal aufrufen:

Legen Sie den pSymbolicLink-Parameter auf NULL fest, und rufen Sie RetrieveSymbolicLink auf. Die Position, auf die pdwSymbolicLinkLengthInChars verweist, empfängt die Anzahl der Zeichen, die der Name des symbolischen Links enthält.
Ordnen Sie einen Puffer zu, der groß genug ist, um den symbolischen Linknamen zu erhalten.
Rufen Sie Erneut RetrieveSymbolicLink auf, und legen Sie den pSymbolicLink-Parameter auf die Adresse des puffers fest, den Sie zugewiesen haben.

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

Beispiele

Das folgende Codebeispiel zeigt, wie die IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival-Rückruffunktion eines Treibers die Länge des symbolischen Linknamens der Geräteschnittstelle bestimmen, einen Puffer für den Namen zuweisen 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
UMDF-Mindestversion	1.9
Kopfzeile	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll

Weitere Informationen

IWDFRemoteInterfaceInitialize

IWDFRemoteInterfaceInitialize::GetInterfaceGuid

Freigeben über