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 controladores UMDF nuevos deben escribirse con 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 con 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 una cadena terminada en NULL que representa el nombre completo del archivo asociado al dispositivo en modo kernel subyacente, si el puntero proporcionado no es NULL 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 apunta pFileName . Si el búfer en pFileName no es NULL, 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 apunta pFileName . Si el controlador proporciona NULL para pFileName y cero para la variable a la que apunta pdwFileNameLengthInChars , 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 era no NULL 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 en pFileName era NULL, el controlador preestablecido la variable en pdwFileNameLengthInChars en 0 y el marco establece la variable en pdwFileNameLengthInChars en el número de caracteres necesarios para la cadena.
RetrieveFileName también podría devolver otros valores HRESULT.
Comentarios
El controlador puede llamar a RetrieveFileName desde su función de devolución de llamada IQueueCallbackCreate::OnCreateFile . Para obtener más información, consulte Uso de interfaces de dispositivo en controladores UMDF.
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 | Value |
|---|---|
| Finalización del soporte técnico | No disponible en UMDF 2.0 y versiones posteriores. |
| Plataforma de destino | Escritorio |
| Versión mínima de UMDF | 1.5 |
| Encabezado | wudfddi.h (incluya Wudfddi.h) |
| Archivo DLL | WUDFx.dll |