Método IShellFolder::GetDisplayNameOf (shobjidl_core.h)

  • Artículo

Recupera el nombre para mostrar del objeto de archivo o subcarpeta especificados.

Sintaxis

HRESULT GetDisplayNameOf(
  [in]  PCUITEMID_CHILD pidl,
  [in]  SHGDNF          uFlags,
  [out] STRRET          *pName
);

Parámetros

[in] pidl

Tipo: PCUITEMID_CHILD

PIDL que identifica de forma única el objeto de archivo o la subcarpeta en relación con la carpeta primaria.

[in] uFlags

Tipo: SHGDNF

Marcas usadas para solicitar el tipo de nombre para mostrar que se va a devolver. Para obtener una lista de valores posibles, consulte el tipo enumerado SHGDNF .

[out] pName

Tipo: STRRET*

Cuando este método devuelve , contiene un puntero a una estructura STRRET en la que se va a devolver el nombre para mostrar. El tipo de nombre devuelto en esta estructura puede ser el tipo solicitado, pero la carpeta Shell podría devolver un tipo diferente.

Valor devuelto

Tipo: HRESULT

Si este método se realiza correctamente, devuelve S_OK. De lo contrario, devuelve un código de error de HRESULT.

Comentarios

Es responsabilidad del autor de la llamada liberar recursos asignados por esta función.

Normalmente, pidl solo puede hacer referencia a los elementos contenidos en la carpeta primaria. El PIDL debe ser de un solo nivel y contener exactamente una estructura SHITEMID seguida de un cero de terminación. Si desea recuperar el nombre para mostrar de un elemento que está más profundo que un nivel fuera de la carpeta primaria, use SHBindToParent para enlazar con la carpeta primaria inmediata del elemento y, a continuación, pase el PIDL de nivel único del elemento a IShellFolder::GetDisplayNameOf.

Además, si la marca de SHGDN_FORPARSING está establecida en uFlags y la marca de SHGDN_INFOLDER no está establecida, pidl puede hacer referencia a un objeto en cualquier nivel debajo de la carpeta primaria de la jerarquía de espacios de nombres. A la vez, pidl podría ser un PIDL de varios niveles, en relación con la carpeta primaria, y podría contener varias estructuras SHITEMID . Sin embargo, ya no se admite y pidl ahora debe hacer referencia solo a un solo elemento secundario.

La manera más sencilla de recuperar el nombre para mostrar de la estructura a la que apunta pName es pasarlo a StrRetToBuf o StrRetToStr. Estas funciones toman una estructura STRRET y devuelven el nombre. También puede examinar el miembro uType de la estructura y recuperar el nombre del miembro adecuado.

Las marcas especificadas en uFlags son sugerencias sobre el uso previsto del nombre. No garantizan que IShellFolder devuelva el formato solicitado del nombre. Si ese formulario no está disponible, es posible que se devuelva otro. En concreto, no hay ninguna garantía de que el nombre devuelto por la marca SHGDN_FORPARSING se analizará correctamente mediante IShellFolder::P arseDisplayName. También hay algunas combinaciones de marcas que podrían hacer que el recorrido de ida y vuelta GetDisplayNameOf/ParseDisplayName no devuelva la lista de identificadores original. Esta repetición es excepcional, pero debe comprobar para asegurarse.

Nota El nombre de análisis que se devuelve cuando uFlags tiene establecido la marca SHGDN_FORPARSING no es necesariamente una cadena de texto normal. Las carpetas virtuales, como Mi equipo, pueden devolver una cadena que contiene el GUID del objeto de carpeta con el formato "::{GUID}". Se recomienda a los desarrolladores que implementen IShellFolder::GetDisplayNameOf devolver nombres de análisis que estén lo más cerca posible de los nombres para mostrar, ya que el usuario final suele tener que escribir o editar estos nombres.
 

Requisitos

Requisito Value
Cliente mínimo compatible Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado shobjidl_core.h (incluya Shobjidl.h)
Archivo DLL Shell32.dll (versión 4.0 o posterior)

Consulte también

IShellFolder

IShellFolder2