Метод IWDFRemoteInterfaceInitialize::RetrieveSymbolicLink (wudfddi.h)

  • Статья

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

Метод RetrieveSymbolicLink извлекает символьное имя ссылки, назначенное операционной системой интерфейсу устройства.

Синтаксис

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

Параметры

[out, optional] pSymbolicLink

Указатель на буфер, получающий символьную строку Юникода, завершающуюся null, которая представляет имя символьной ссылки. Присвойте этому указателю значение NULL , чтобы получить требуемый размер буфера.

[in, out] pdwSymbolicLinkLengthInChars

Указатель на расположение, выделенное вызывающим объектом. На входных данных это расположение должно содержать заданную вызывающим объектом длину буфера, на который указывает pSymbolicLink . В выходных данных расположение получает длину (в символах) символьного имени ссылки, включая завершающий символ NULL .

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

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

Код возврата Описание
E_NOT_SUFFICIENT_BUFFER
 Буфер, на который указывает pSymbolicLink , слишком мал. В этом случае платформа сохраняет требуемый размер буфера в расположении, на которое указывает pdwSymbolicLinkLengthInChars .
 

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

Комментарии

Имя символьной ссылки может содержать добавленный символ обратной косой черты (), за которым следует строка ссылки для конкретного экземпляра.

Как правило, драйвер должен вызывать RetrieveSymbolicLink дважды, как показано ниже.

  1. Задайте для параметра pSymbolicLinkзначение NULL и вызовите RetrieveSymbolicLink. Расположение, на которое указывает pdwSymbolicLinkLengthInChars , получает количество символов, содержащихся в имени символьной ссылки.
  2. Выделите буфер, который достаточно велик для получения имени символьной ссылки.
  3. Снова вызовите RetrieveSymbolicLink и задайте для параметра pSymbolicLink адрес выделенного буфера.
Дополнительные сведения о методе RetrieveSymbolicLink см. в статье Использование интерфейсов устройств в драйверах на основе UMDF.

Примеры

В следующем примере кода показано, как функция обратного вызова IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival может определить длину символьного имени ссылки интерфейса устройства, выделить буфер для имени, а затем получить имя.

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:
...
}

Требования

Требование Значение
Дата окончания поддержки Недоступно в UMDF 2.0 и более поздних версиях.
Целевая платформа Персональный компьютер
Минимальная версия UMDF 1,9
Верхняя часть wudfddi.h (включая Wudfddi.h)
DLL WUDFx.dll

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

IWDFRemoteInterfaceInitialize

IWDFRemoteInterfaceInitialize::GetInterfaceGuid