IWDFDevice2::CreateSymbolicLinkWithReferenceString-Methode (wudfddi.h)

[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.]

DieCreateSymbolicLinkWithReferenceString-Methode erstellt einen symbolischen Linknamen und optional eine Verweiszeichenfolge für ein Gerät.

Syntax

HRESULT CreateSymbolicLinkWithReferenceString(
  [in]           PCWSTR pSymbolicLink,
  [in, optional] PCWSTR pReferenceString
);

Parameter

[in] pSymbolicLink

Ein Zeiger auf eine NULL-Zeichenfolge, die zum vom Benutzer sichtbaren Namen des Geräts wird. Der symbolische Linkname muss sich im globalen DosDevices-Namespace befinden.

[in, optional] pReferenceString

Ein Zeiger auf eine NULL-Zeichenfolge, die Windows an den Gerätenamen anfüge, wenn eine Anwendung den symbolischen Namen verwendet, den der pSymbolicLink-Parameter angibt. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise". Dieser Parameter ist optional und kann NULL sein.

Rückgabewert

CreateSymbolicLinkWithReferenceString gibt S_OK zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt die Methode möglicherweise einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
E_INVALIDARG	Der Aufrufer hat einen ungültigen Wert für einen Eingabeparameter angegeben.
E_OUTOFMEMORY	Fehler bei der Speicherzuordnung.

 

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

Hinweise

CreateSymbolicLinkWithReferenceString erstellt einen symbolischen Linknamen und optional eine Verweiszeichenfolge für das Gerät, das die IWDFDevice2-Schnittstelle darstellt. Nachdem ein Treiber CreateSymbolicLinkWithReferenceString aufgerufen hat, können Anwendungen den symbolischen Linknamen verwenden, um auf das Gerät zuzugreifen.

Angenommen, der Name Ihres Geräts lautet "\Device\MyDevice". Sie können einen symbolischen Linknamen für "DeviceUserName" für Ihr Gerät erstellen, indem Sie "L"DeviceUserName"" für den pSymbolicLink-Parameter angeben. Wenn Sie "L"Instance3"" für den Parameter pReferenceString angeben, erstellen Sie einen symbolischen Link zu \Device\MyDevice\Instance3. Wenn eine Anwendung das Gerät mithilfe des symbolischen Linknamens öffnet, öffnet der E/A-Manager \Device\MyDevice und erstellt ein WDM-Dateiobjekt, das die Zeichenfolge \Instance3 als Dateinamen enthält. Ihr UMDF-basierter Treiber empfängt ein vom Framework erstelltes Dateiobjekt, das auch die Zeichenfolge \Instance3 als Dateinamen enthält (siehe IWDFFile::RetrieveFileName).

Frameworkbasierte Treiber stellen in der Regel Geräteschnittstellen bereit, die Anwendungen für den Zugriff auf ihre Geräte verwenden können, anstatt symbolische Links bereitzustellen.

Wenn das Gerät unerwartet entfernt wird (überraschend entfernt), entfernt das Framework den symbolischen Link zum Gerät. Der Treiber kann dann den symbolischen Linknamen für eine neue instance des Geräts verwenden.

Wenn Sie keine Verweiszeichenfolge zum symbolischen Linknamen Ihres Geräts hinzufügen müssen, kann Ihr Treiber IWDFDevice::CreateSymbolicLink anstelle von CreateSymbolicLinkWithReferenceString aufrufen.

Beispiele

Die folgende Zeile definiert ein symbolisches Linknamenpräfix im globalen DosDevices-Namespace .

#define SYMBOLIC_LINK_NAME_PREFIX   L"\\DosDevices\\Global\\"

Im folgenden Codebeispiel wird eine symbolische Namenszeichenfolge erstellt, die IWDFDevice2-Schnittstelle abgerufen und dann CreateSymbolicLinkWithReferenceString aufgerufen.

    IWDFDevice2 *pDevice2 = NULL;
    HRESULT hr;

    //
    // Create symbolic link name string.
    //
    hr = StringCchPrintf(portFullName,
                         portFullNameLength,
                         L"%ws%ws",
                         SYMBOLIC_LINK_NAME_PREFIX,
                         portName);
    if (FAILED(hr))
    {
        goto Exit;
    }

    //
    // Get a pointer to the IWDFDevice2 interface.
    //
    hr = pIWDFDevice->QueryInterface(__uuidof(IWDFDevice2),
                                     (void**) &pDevice2);
    if (SUCCEEDED(hr)) 
    {
    hr = pDevice2->CreateSymbolicLinkWithReferenceString(portFullName,
                                                         portCountString);
    if (FAILED(hr))
        {
            goto Exit;
        }
        SAFE_RELEASE(pDevice2);
    }

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

IWDFDevice2

IWDFDevice::CreateSymbolicLink