Метод IWDFDevice2::CreateSymbolicLinkWithReferenceString (wudfddi.h)

Статья
02/07/2025

[ предупреждение: UMDF 2 является последней версией UMDF и заменяет UMDF 1. Все новые драйверы UMDF должны быть написаны с помощью UMDF 2. Новые функции не добавляются в UMDF 1, а поддержка UMDF 1 в более новых версиях Windows 10 ограничена. Универсальные драйверы Windows должны использовать UMDF 2. Дополнительные сведения см. в разделе Начало работы с UMDF.]

МетодCreateSymbolicLinkWithReferenceString создает символьное имя ссылки и при необходимости ссылку на устройство.

Синтаксис

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

Параметры

[in] pSymbolicLink

Указатель на строку символов , завершающуюNULL, которая становится видимым пользователем именем устройства. Имя символьной ссылки должно находиться в глобальном пространстве имен DosDevices.

[in, optional] pReferenceString

Указатель на строку символа null NULL, которую Windows добавляет к имени устройства, когда приложение использует символьное имя, указанное параметром pSymbolicLink. Дополнительные сведения см. в следующем разделе "Примечания". Этот параметр является необязательным и может быть null.

Возвращаемое значение

CreateSymbolicLinkWithReferenceString возвращает S_OK, если операция завершится успешно. В противном случае метод может вернуть одно из следующих значений:

Возвращаемый код	Описание
E_INVALIDARG	Вызывающий объект указал недопустимое значение для входного параметра.
E_OUTOFMEMORY	Сбой выделения памяти.

Этот метод может возвращать одно из других значений, содержащихся в Winerror.h.

Замечания

CreateSymbolicLinkWithReferenceString создает символьное имя ссылки и при необходимости ссылку на строку для устройства, представляющего интерфейс IWDFDevice2. После вызова драйвера CreateSymbolicLinkWithReferenceStringприложения могут использовать имя символьной ссылки для доступа к устройству.

Предположим, что имя устройства — \Device\MyDevice. Вы можете создать символьное имя "DeviceUserName" для устройства, указав "L"DeviceUserName" для параметра pSymbolicLink. Если для параметра pReferenceString задано значение "L"Instance3", создается символьная ссылка на \Device\MyDevice\Instance3. Если приложение открывает устройство с помощью символьного имени ссылки, диспетчер ввода-вывода открывает \Device\MyDevice и создает объект WDM-файла, содержащий строку \Instance3 в качестве имени файла. Драйвер на основе UMDF получает созданный платформой объект файла, который также содержит строку \Instance3 в качестве имени файла (см. IWDFFile::RetrieveFileName).

Как правило, вместо предоставления символьных ссылок драйверы на основе платформы предоставляют интерфейсы устройств, которые приложения могут использовать для доступа к своим устройствам.

Если устройство удалено неожиданно (неожиданно удалено), платформа удаляет символьную ссылку на устройство. Затем драйвер может использовать символьное имя ссылки для нового экземпляра устройства.

Если вам не нужно добавлять ссылку на символьное имя устройства, драйвер может вызывать IWDFDevice::CreateSymbolicLink вместо CreateSymbolicLinkWithReferenceString.

Примеры

Следующая строка определяет префикс имени символьной ссылки в глобальном DosDevices пространстве имен.

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

Следующий пример кода создает символьную строку имени, получает интерфейс IWDFDevice2, а затем вызывает CreateSymbolicLinkWithReferenceString.


    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);
    }

Требования

Требование	Ценность
завершение поддержки	Недоступно в UMDF 2.0 и более поздних версиях.
целевая платформа	Настольный
минимальная версия UMDF	1.9
заголовка	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll

См. также

IWDFDevice2

IWDFDevice::CreateSymbolicLink

Поделиться через