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

[Предупреждение: 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, которую Windows добавляет к имени устройства, когда приложение использует символьное имя, заданное параметром pSymbolicLink . Дополнительные сведения см. в разделе "Примечания". Этот параметр является необязательным и может иметь значение NULL.

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

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

Этот метод может возвращать одно из других значений, содержащихся в 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);
    }

Требования

См. также раздел

IWDFDevice2

IWDFDevice::CreateSymbolicLink