Función SetNamedPipeHandleState (namedpipeapi.h)

Artículo
03/08/2023

Establece el modo de lectura y el modo de bloqueo de la canalización con nombre especificada. Si el identificador especificado es al final del cliente de una canalización con nombre y si el proceso del servidor de canalización con nombre está en un equipo remoto, la función también se puede usar para controlar el almacenamiento en búfer local.

Sintaxis

BOOL SetNamedPipeHandleState(
  [in]           HANDLE  hNamedPipe,
  [in, optional] LPDWORD lpMode,
  [in, optional] LPDWORD lpMaxCollectionCount,
  [in, optional] LPDWORD lpCollectDataTimeout
);

Parámetros

[in] hNamedPipe

Identificador de la instancia de canalización con nombre. Este parámetro puede ser un identificador para el extremo del servidor de la canalización, tal como lo devuelve la función CreateNamedPipe , o al final de la canalización del cliente, tal y como devuelve la función CreateFile . El identificador debe tener GENERIC_WRITE acceso a la canalización con nombre para una canalización de solo escritura o de lectura y escritura, o bien debe tener GENERIC_READ y FILE_WRITE_ATTRIBUTES acceso para una canalización de solo lectura.

Este parámetro también puede ser un identificador de una canalización anónima, tal como lo devuelve la función CreatePipe .

[in, optional] lpMode

Nuevo modo de canalización. El modo es una combinación de una marca de modo de lectura y una marca en modo de espera. Este parámetro puede ser NULL si no se establece el modo. Especifique uno de los siguientes modos.

Mode	Significado
PIPE_READMODE_BYTE 0x00000000	Los datos se leen desde la canalización como una secuencia de bytes. Este modo es el valor predeterminado si no se especifica ninguna marca de modo de lectura.
PIPE_READMODE_MESSAGE 0x00000002	Los datos se leen desde la canalización como un flujo de mensajes. Se produce un error en la función si se especifica esta marca para una canalización de tipo byte.

Se puede especificar uno de los siguientes modos de espera.

Mode	Significado
PIPE_WAIT 0x00000000	El modo de bloqueo está habilitado. Este modo es el valor predeterminado si no se especifica ninguna marca de modo de espera. Cuando se especifica un identificador de canalización de modo de bloqueo en la función ReadFile, WriteFile o ConnectNamedPipe , las operaciones no finalizan hasta que haya datos para leer, se escriben todos los datos o se conecta un cliente. El uso de este modo puede significar esperar indefinidamente en algunas situaciones para que un proceso de cliente realice una acción.
PIPE_NOWAIT 0x00000001	El modo de no bloqueo está habilitado. En este modo, ReadFile, WriteFile y ConnectNamedPipe siempre se devuelven inmediatamente. Tenga en cuenta que el modo de no bloqueo es compatible con Microsoft LAN Manager versión 2.0 y no debe usarse para lograr entradas y salidas asincrónicas (E/S) con canalizaciones con nombre.

Mode

Significado

PIPE_WAIT
0x00000000

El modo de bloqueo está habilitado. Este modo es el valor predeterminado si no se especifica ninguna marca de modo de espera. Cuando se especifica un identificador de canalización de modo de bloqueo en la función ReadFile, WriteFile o ConnectNamedPipe , las operaciones no finalizan hasta que haya datos para leer, se escriben todos los datos o se conecta un cliente. El uso de este modo puede significar esperar indefinidamente en algunas situaciones para que un proceso de cliente realice una acción.

PIPE_NOWAIT
0x00000001

El modo de no bloqueo está habilitado. En este modo, ReadFile, WriteFile y ConnectNamedPipe siempre se devuelven inmediatamente. Tenga en cuenta que el modo de no bloqueo es compatible con Microsoft LAN Manager versión 2.0 y no debe usarse para lograr entradas y salidas asincrónicas (E/S) con canalizaciones con nombre.

[in, optional] lpMaxCollectionCount

Número máximo de bytes recopilados en el equipo cliente antes de la transmisión al servidor. Este parámetro debe ser NULL si el identificador de canalización especificado es al final del servidor de una canalización con nombre o si los procesos de cliente y servidor están en la misma máquina. Este parámetro se omite si el proceso de cliente especifica la marca FILE_FLAG_WRITE_THROUGH en la función CreateFile cuando se creó el identificador. Este parámetro puede ser NULL si no se establece el recuento de colecciones.

[in, optional] lpCollectDataTimeout

El tiempo máximo, en milisegundos, que puede pasar antes de que una canalización remota con nombre transfiera información a través de la red. Este parámetro debe ser NULL si el identificador de canalización especificado es al final del servidor de una canalización con nombre o si los procesos de cliente y servidor están en el mismo equipo. Este parámetro se omite si el proceso de cliente especificó la marca FILE_FLAG_WRITE_THROUGH en la función CreateFile cuando se creó el identificador. Este parámetro puede ser NULL si no se establece el recuento de colecciones.

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

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.

Ejemplos

Para obtener un ejemplo, vea Cliente de canalización con nombre.

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