Método IWDFFile::RetrieveFileName (wudfddi.h)
[Advertencia: UMDF 2 es la versión más reciente de UMDF y sustituye a UMDF 1. Todos los nuevos controladores UMDF deben escribirse mediante UMDF 2. No se agregan nuevas características a UMDF 1 y hay compatibilidad limitada con UMDF 1 en versiones más recientes de Windows 10. Los controladores universales de Windows deben usar UMDF 2. Para obtener más información, consulta Introducción a UMDF.]
El método RetrieveFileName recupera el nombre completo del archivo asociado al dispositivo en modo kernel subyacente.
Sintaxis
HRESULT RetrieveFileName(
[out] PWSTR pFileName,
[in, out] DWORD *pdwFileNameLengthInChars
);
Parámetros
[out] pFileName
Puntero a un búfer proporcionado por el autor de la llamada que recibe un cadena terminadaNULL que representa el nombre completo del archivo asociado al dispositivo en modo kernel subyacente, si el puntero proporcionado no esnull y RetrieveFileName se realiza correctamente.
[in, out] pdwFileNameLengthInChars
Puntero a una variable proporcionada por el autor de la llamada que recibe el tamaño, en caracteres, del nombre de archivo completo al que pFileName apunta. Si el búfer de pFileName no esNULL, el marco devuelve el tamaño, en caracteres, de la cadena de nombre de archivo.
En la entrada, el controlador establece esta variable en el tamaño, en caracteres, del búfer al que pFileName apunta. Si el controlador proporciona NULL para pFileName y cero para la variable a la que pdwFileNameLengthInChars apunta, el marco establece la variable en el tamaño, en caracteres, que requiere la cadena de nombre de archivo.
Valor devuelto
RetrieveFileName devuelve S_OK para los escenarios siguientes:
- El búfer al que apunta el parámetro pFileName no eraNULL y lo suficientemente grande como para contener la cadena de nombre, incluido el carácter NULL y el marco copió correctamente la cadena en el búfer proporcionado y estableció la variable a la que apunta el parámetro pdwFileNameLengthInChars al número de caracteres de la cadena.
- El búfer de pFileName era NULL, el controlador preestablecido la variable en pdwFileNameLengthInChars en 0 y el marco establece la variable en pdwFileNameLengthInChars al número de caracteres necesarios para la cadena.
RetrieveFileName también puede devolver otros valores HRESULT.
Observaciones
El controlador puede llamar a RetrieveFileName desde su IQueueCallbackCreate::OnCreateFile función de devolución de llamada. Para obtener más información, consulte Using Device Interfaces in UMDF Drivers.
Ejemplos
En el ejemplo de código siguiente se muestra cómo recuperar el nombre de un archivo.
ULONG fileNameCch = 0;
PWSTR fileName = NULL;
ULONG index;
CComObject<CUmdfHidFile> *file = NULL;
HRESULT hr;
// Get the length of the file name to allocate a buffer.
hr = WdfFile->RetrieveFileName(NULL, &fileNameCch);
//
// Allocate the buffer.
//
if (SUCCEEDED(hr))
{
fileName = new WCHAR[fileNameCch];
if (fileName == NULL)
{
hr = E_OUTOFMEMORY;
}
}
//
// Get the file name.
//
if (SUCCEEDED(hr))
{
hr = WdfFile->RetrieveFileName(fileName, &fileNameCch);
}
Requisitos
| Requisito | Valor |
|---|---|
| fin del soporte técnico | No disponible en UMDF 2.0 y versiones posteriores. |
| de la plataforma de destino de | Escritorio |
| versión mínima de UMDF | 1.5 |
| encabezado de | wudfddi.h (incluya Wudfddi.h) |
| DLL de | WUDFx.dll |