Función CreatePipe (namedpipeapi.h)

Artículo
03/08/2023

Crea una canalización anónima y devuelve identificadores a los extremos de lectura y escritura de la canalización.

Sintaxis

BOOL CreatePipe(
  [out]          PHANDLE               hReadPipe,
  [out]          PHANDLE               hWritePipe,
  [in, optional] LPSECURITY_ATTRIBUTES lpPipeAttributes,
  [in]           DWORD                 nSize
);

Parámetros

[out] hReadPipe

Puntero a una variable que recibe el identificador de lectura de la canalización.

[out] hWritePipe

Puntero a una variable que recibe el identificador de escritura de la canalización.

[in, optional] lpPipeAttributes

Puntero a una estructura de SECURITY_ATTRIBUTES que determina si los procesos secundarios pueden heredar el identificador devuelto. Si lpPipeAttributes es NULL, no se puede heredar el identificador.

El miembro lpSecurityDescriptor de la estructura especifica un descriptor de seguridad para la nueva canalización. Si lpPipeAttributes es NULL, la canalización obtiene un descriptor de seguridad predeterminado. Las ACL del descriptor de seguridad predeterminado para una canalización proceden del token principal o de suplantación del creador.

[in] nSize

Tamaño del búfer de la canalización, en bytes. El tamaño es solo una sugerencia; el sistema usa el valor para calcular un mecanismo de almacenamiento en búfer adecuado. Si este parámetro es cero, el sistema usa el tamaño de búfer predeterminado.

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

CreatePipe crea la canalización, asignando el tamaño de canalización especificado al búfer de almacenamiento. CreatePipe también crea identificadores que el proceso usa para leer y escribir en el búfer en llamadas posteriores a las funciones ReadFile y WriteFile .

Para leer desde la canalización, un proceso usa el identificador de lectura en una llamada a la función ReadFile . ReadFile devuelve cuando se cumple una de las siguientes condiciones: se completa una operación de escritura en el extremo de escritura de la canalización, el número de bytes solicitados se ha leído o se produce un error.

Cuando un proceso usa WriteFile para escribir en una canalización anónima, la operación de escritura no se completa hasta que se escriben todos los bytes. Si el búfer de canalización está lleno antes de que se escriban todos los bytes, WriteFile no devuelve hasta que otro proceso o subproceso usa ReadFile para que haya más espacio de búfer disponible.

Las canalizaciones anónimas se implementan mediante una canalización con nombre con un nombre único. Por lo tanto, a menudo puede pasar un identificador a una canalización anónima a una función que requiere un identificador para una canalización con nombre.

Si se produce un error en CreatePipe , el contenido de los parámetros de salida es indeterminado. No se deben realizar suposiciones sobre su contenido en este evento.

Para liberar recursos usados por una canalización, la aplicación siempre debe cerrar los identificadores cuando ya no sean necesarios, lo que se logra mediante una llamada a la función CloseHandle o cuando finaliza el proceso asociado con los identificadores de instancia. Tenga en cuenta que una instancia de una canalización puede tener más de un identificador asociado. Siempre se elimina una instancia de una canalización cuando se cierra el último identificador de la instancia de la canalización con nombre.

Ejemplos

Para obtener un ejemplo, vea Crear un proceso secundario con entrada y salida redirigidas.

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