Función PeekNamedPipe (namedpipeapi.h)

Artículo
02/29/2024

Copia datos de una canalización con nombre o anónima en un búfer sin quitarlos de la canalización. También devuelve información sobre los datos de la canalización.

Sintaxis

BOOL PeekNamedPipe(
  [in]            HANDLE  hNamedPipe,
  [out, optional] LPVOID  lpBuffer,
  [in]            DWORD   nBufferSize,
  [out, optional] LPDWORD lpBytesRead,
  [out, optional] LPDWORD lpTotalBytesAvail,
  [out, optional] LPDWORD lpBytesLeftThisMessage
);

Parámetros

[in] hNamedPipe

Identificador de la canalización. Este parámetro puede ser un identificador de una instancia de canalización con nombre, tal como lo devuelve la función CreateNamedPipe o CreateFile , o bien puede ser un identificador para el extremo de lectura de una canalización anónima, tal y como devuelve la función CreatePipe . El identificador debe tener GENERIC_READ acceso a la canalización.

[out, optional] lpBuffer

Puntero a un búfer que recibe los datos leídos de la canalización. Este parámetro puede ser NULL si no se va a leer ningún dato.

[in] nBufferSize

Tamaño del búfer especificado por el parámetro lpBuffer , en bytes. Este parámetro se omite si lpBuffer es NULL.

[out, optional] lpBytesRead

Puntero a una variable que recibe el número de bytes leídos de la canalización. Este parámetro puede ser NULL si no se va a leer ningún dato.

[out, optional] lpTotalBytesAvail

Puntero a una variable que recibe el número total de bytes disponibles para leerse desde la canalización. Este parámetro puede ser NULL si no se va a leer ningún dato.

[out, optional] lpBytesLeftThisMessage

Puntero a una variable que recibe el número de bytes restantes en este mensaje. Este parámetro será cero para canalizaciones con nombre de tipo byte o para canalizaciones anónimas. Este parámetro puede ser NULL si no se va a leer ningún dato.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Comentarios

La función PeekNamedPipe es similar a la función ReadFile con las siguientes excepciones:

Los datos se leen en el modo especificado con CreateNamedPipe. Por ejemplo, cree una canalización con PIPE_TYPE_MESSAGE | PIPE_READMODE_MESSAGE. Si cambia el modo a PIPE_READMODE_BYTE con SetNamedPipeHandleState, ReadFile leerá en modo de bytes, pero PeekNamedPipe seguirá leyendo en modo de mensaje.
Los datos leídos de la canalización no se quitan del búfer de la canalización.
La función puede devolver información adicional sobre el contenido de la canalización.
La función siempre devuelve inmediatamente en una aplicación de un solo subproceso, incluso si no hay datos en la canalización. El modo de espera de un controlador de canalización con nombre (bloqueo o bloqueo) no tiene ningún efecto en la función.

Nota La función PeekNamedPipe puede bloquear la ejecución de subprocesos de la misma manera que cualquier función de E/S cuando se llama en un identificador sincrónico en una aplicación multiproceso. Para evitar esta condición, use un identificador de canalización creado para E/S asincrónica.

Si el identificador especificado es un identificador de canalización con nombre en modo de lectura de bytes, la función lee todos los bytes disponibles hasta el tamaño especificado en nBufferSize. Para un identificador de canalización con nombre en modo de lectura de mensajes, la función lee el siguiente mensaje de la canalización. Si el mensaje es mayor que nBufferSize, la función devuelve TRUE después de leer el número especificado de bytes. En esta situación, lpBytesLeftThisMessage recibirá el número de bytes restantes en el mensaje.

Windows 10, versión 1709: las canalizaciones solo se admiten en un contenedor de aplicaciones; es decir, desde un proceso de UWP a otro proceso de UWP que forma parte de la misma aplicación. Además, las canalizaciones con nombre deben usar la sintaxis \\.\pipe\LOCAL\ para el nombre de la canalización.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [aplicaciones de escritorio \| Aplicaciones para UWP]
Servidor mínimo compatible	Windows 2000 Server [aplicaciones de escritorio \| Aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	namedpipeapi.h
Library	Kernel32.lib
Archivo DLL	Kernel32.dll