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

Статья
03/01/2024

[Предупреждение: 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.

Задайте для параметра pSymbolicLinkзначение NULL и вызовите RetrieveSymbolicLink. Расположение, на которое указывает pdwSymbolicLinkLengthInChars , получает количество символов, содержащихся в имени символьной ссылки.
Выделите буфер, который достаточно велик для получения имени символьной ссылки.
Снова вызовите 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

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