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

Статья
02/07/2025

[ предупреждение: 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 дважды, как показано ниже.

Задайте параметру 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 (include Wudfddi.h)
DLL	WUDFx.dll

См. также

IWDFRemoteInterfaceInitialize

IWDFRemoteInterfaceInitialize::GetInterfaceGuid

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