Función TransactNamedPipe (namedpipeapi.h)

Artículo
03/08/2023

Combina las funciones que escriben un mensaje en y leen un mensaje de la canalización con nombre especificada en una sola operación.

Sintaxis

BOOL TransactNamedPipe(
  [in]                HANDLE       hNamedPipe,
  [in]                LPVOID       lpInBuffer,
  [in]                DWORD        nInBufferSize,
  [out]               LPVOID       lpOutBuffer,
  [in]                DWORD        nOutBufferSize,
  [out]               LPDWORD      lpBytesRead,
  [in, out, optional] LPOVERLAPPED lpOverlapped
);

Parámetros

[in] hNamedPipe

Identificador de la canalización con nombre devuelta por la función CreateNamedPipe o CreateFile .

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

[in] lpInBuffer

Puntero al búfer que contiene los datos que se van a escribir en la canalización.

[in] nInBufferSize

Tamaño del búfer de entrada, en bytes.

[out] lpOutBuffer

Puntero al búfer que recibe los datos leídos de la canalización.

[in] nOutBufferSize

Tamaño del búfer de salida, en bytes.

[out] lpBytesRead

Puntero a la variable que recibe el número de bytes leídos de la canalización.

Si lpOverlapped es NULL, lpBytesRead no puede ser NULL.

Si lpOverlapped no es NULL, lpBytesRead puede ser NULL. Si se trata de una operación de lectura superpuesta, puede obtener el número de bytes leídos llamando a GetOverlappedResult. Si hNamedPipe está asociado a un puerto de finalización de E/S, puede obtener el número de bytes leídos llamando a GetQueuedCompletionStatus.

[in, out, optional] lpOverlapped

Puntero a una estructura OVERLAPPED. Esta estructura es necesaria si hNamedPipe se abrió con FILE_FLAG_OVERLAPPED.

Si hNamedPipe se abrió con FILE_FLAG_OVERLAPPED, el parámetro lpOverlapped no debe ser NULL. Debe apuntar a una estructura SUPERPUESTA válida. Si hNamedPipe se creó con FILE_FLAG_OVERLAPPED y lpOverlapped es NULL, la función puede informar incorrectamente de que la operación se ha completado.

Si hNamedPipe se abrió con FILE_FLAG_OVERLAPPED y lpOverlapped no es NULL, TransactNamedPipe se ejecuta como una operación superpuesta. La estructura SUPERPUESTA debe contener un objeto de evento de restablecimiento manual (que se puede crear mediante la función CreateEvent ). Si la operación no se puede completar inmediatamente, TransactNamedPipe devuelve FALSE y GetLastError devuelve ERROR_IO_PENDING. En esta situación, el objeto de evento se establece en el estado no asignado antes de que TransactNamedPipe devuelva y se establece en el estado señalado cuando la transacción ha finalizado. Además, se puede recibir una notificación cuando se completa una operación superpuesta mediante las funciones GetQueuedCompletionStatus o GetQueuedCompletionStatusEx . En este caso, no es necesario asignar el evento de restablecimiento manual en la estructura SUPERPUESTA y la finalización se produce en hNamedPipe de la misma manera que una operación asincrónica de lectura o escritura. Para obtener más información sobre las operaciones superpuestas, consulte Canalizaciones.

Si hNamedPipe no se abrió con FILE_FLAG_OVERLAPPED, TransactNamedPipe no devuelve hasta que se complete la operación.

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.

Si el mensaje que se va a leer es mayor que el búfer especificado por el parámetro nOutBufferSize , TransactNamedPipe devuelve FALSE y la función GetLastError devuelve ERROR_MORE_DATA. El resto del mensaje se puede leer mediante una llamada posterior a ReadFile, ReadFileEx o PeekNamedPipe.

Comentarios

TransactNamedPipe produce un error si el servidor no creó la canalización como una canalización de tipo mensaje o si el identificador de canalización no está en modo de lectura de mensajes. Por ejemplo, si un cliente se ejecuta en la misma máquina que el servidor y usa el formato \.\pipe\pipename para abrir la canalización, la canalización se abre en modo byte mediante el sistema de archivos de canalización con nombre (NPFS). Si el cliente usa el formulario \\server\pipe\pipename, el redirector abre la canalización en modo de mensaje. Un identificador de canalización de modo de bytes se puede cambiar al modo de lectura de mensajes con la función SetNamedPipeHandleState .

La función no se puede completar correctamente hasta que los datos se escriben en el búfer especificado por el parámetro lpOutBuffer . El parámetro lpOverlapped está disponible para permitir que el subproceso de llamada realice otras tareas mientras la operación se ejecuta en segundo plano.

El tamaño máximo garantizado de una transacción de tubería con nombre es de 64 kilobytes. En algunos casos limitados, las transacciones más allá de 64 kilobytes son posibles, en función de las versiones del sistema operativo que participen en las condiciones de la transacción y de la red dinámica. Sin embargo, no hay ninguna garantía de que las transacciones por encima de 64 kilobytes se realicen correctamente. Por lo tanto, se recomienda limitar las transacciones de canalización con nombre a 64 kilobytes de datos.

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, consulte Transacciones en canalizaciones 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