NamedPipeClientConnection class

One client-side connection to a named pipe. Produced by NamedPipeClientManager.Connect. Carries the connection-lifecycle events (Connected, Disconnected) and the message events (MessageReceived, MessageSent), plus the AsyncRead / AsyncWrite / AsyncClose methods that drive them.

The class is tagged [COMCreatable(False)] and its constructor takes a package-private interface — reach instances only through NamedPipeClientManager.Connect.

Important

The package _README.txt states: “you MUST call AsyncClose on the client side, otherwise the connection is left alive when the object goes out of scope”. Either call AsyncClose explicitly before dropping the last reference, or let the object terminate cleanly through its Class_Terminate (which calls AsyncClose automatically). Holding the reference forever — in a module-level Collection, for example — without calling AsyncClose keeps the pipe handle open and the IOCP thread alive.

See the package overview for the IOCP / event-marshalling architecture, the cookie correlation pattern, and the transient lifetime of Data() As Byte inside events.

Properties

CustomData

A per-connection opaque slot the consumer can attach state to — typically a session object or a pending-replies dictionary tied to this one connection. Variant, default Empty. The package never reads or writes this field.

Handle

The underlying Win32 file handle returned by CreateFileW("\\.\pipe\<PipeName>"). LongPtr. Exposed for low-level / debugging use — most consumers can ignore it. Do not call CloseHandle on this value yourself; use AsyncClose so the IOCP loop and the parent manager’s bookkeeping stay consistent.

PipeName

The leaf pipe name this connection was opened against — the same value that was passed to NamedPipeClientManager.Connect. String. Read-only in practice; the package sets it from the constructor argument and never changes it.

Events

Connected

Fires once the asynchronous CreateFileW started by NamedPipeClientManager.Connect has succeeded and the pipe is ready for message exchange.

Syntax: connection_Connected()

Disconnected

Fires once the pipe has dropped and every outstanding asynchronous I/O against the connection has returned. The connection object is no longer usable for I/O after this event.

Syntax: connection_Disconnected()

MessageReceived

Fires when a complete message has been read from the pipe.

Syntax: connection_MessageReceived(ByRef Cookie As Variant, ByRef Data() As Byte)

Cookie
The opaque correlation value originally passed to the AsyncRead that produced this read — or Empty if the read came from the auto-issued reads driven by NamedPipeClientManager.ContinuouslyReadFromPipe.
Data
The message payload. See Working with Data() As Byte in events on the package overview for the transient-buffer lifetime caveat — copy the bytes out before the handler returns if you need them.

MessageSent

Fires when a previously-issued AsyncWrite has completed.

Syntax: connection_MessageSent(ByRef Cookie As Variant)

Cookie
The opaque correlation value that was passed to the originating AsyncWrite call.

Methods

AsyncClose

Cancels every outstanding I/O against this connection and closes the underlying pipe handle. Eventually triggers the Disconnected event once the cancellation completes. Automatically invoked from Class_Terminate when the last reference to the connection drops.

Syntax: connection.AsyncClose

Important

See the class intro: the README requires that either this method runs (explicitly, or through Class_Terminate) before the connection is considered finished.

AsyncRead

Manually issues an asynchronous read against this connection.

Syntax: connection.AsyncRead [ Cookie [, OverlappedStruct ] ]

Cookie
optional A Variant correlation value, surfaced as the Cookie parameter of the matching MessageReceived event. Default Empty.
OverlappedStruct
optional A LongPtr to a pre-allocated OVERLAPPED_CUSTOM structure. Internal use only — the IOCP machinery passes this when re-issuing a read after ERROR_MORE_DATA. Consumer code should always omit this parameter.

Only needed when the parent manager’s ContinuouslyReadFromPipe is False; otherwise the IOCP loop keeps a read pending automatically and explicit calls are redundant.

AsyncWrite

Sends a message to the server.

Syntax: connection.AsyncWrite Data() [, Cookie ]

Data
required A Byte() array carrying the bytes to send. An uninitialised or zero-length array is a no-op.
Cookie
optional A Variant correlation value, surfaced as the Cookie parameter of the matching MessageSent event. Default Empty.

Returns immediately; the actual transmission runs through the IOCP loop. The completion fires MessageSent on this connection.

See Also