class io.NamedPipe

Overview

This class provides high-level asynchronous interface for the server side of Windows named pipes. Windows named pipes are widely used for IPC(Inter-Process Communications) between applications, services and drivers on Windows platform. More…

import "io_base.jncx"
import "io_NamedPipe.jnc"

class NamedPipe {
    // fields

    io.NamedPipeEvents readonly volatile m_activeEvents;
    std.Error const* readonly volatile m_ioError;
    bool readonly m_isOpen;

    // properties

    uint_t autoget property m_backLogLimit;
    uint_t autoget property m_readParallelism;
    size_t autoget property m_readBlockSize;
    size_t autoget property m_readBufferSize;
    size_t autoget property m_writeBufferSize;
    io.FileStreamOptions autoget property m_options;

    // construction

    construct();
    destruct();

    // methods

    bool errorcode open(string_t name);
    void close();
    io.FileStream* accept(bool isSuspended = false);

    long errorcode wait(
        io.NamedPipeEvents eventMask,
        void function* handler(io.NamedPipeEvents triggeredEvents)
    );

    bool errorcode cancelWait(long handle);

    io.NamedPipeEvents blockingWait(
        io.NamedPipeEvents eventMask,
        uint_t timeout = -1
    );

    import io.NamedPipe.NamedPipeEvents async asyncWait(io.NamedPipeEvents eventMask);

    // aliases

    alias dispose = close;
};

Detailed Documentation

This class provides high-level asynchronous interface for the server side of Windows named pipes. Windows named pipes are widely used for IPC(Inter-Process Communications) between applications, services and drivers on Windows platform.

For working from the client side of a named pipe, please use io.File class.

A typical sequence of steps when working with a named pipe server looks something like this:

  • Open a server-side named pipe with open method;

  • Assign IO event handler with wait method. You would probably also want to schedule your event handler to be run in particular environment(e.g., in a specific thread) and partially apply some syncrhonization ID to discard late events;

  • When io.NamedPipeEvents.IncomingConnection event is fired, accept a client connection using accept method;

  • Communicate with the client via io.FileStream returned by accept;

  • Close named pipe server and accepted client file streams when no longer needed with close method.

See also:

io.NamedPipeEvents, io.File, io.FileStream

Fields

bool readonly m_isOpen

Holds the open status for serial port, i.e. true if opened; false otherwise.

Methods

bool errorcode open(string_t name)

Opens server-side named pipe(s), effectively starting a named pipe server.

The function accepts three arguments. The first one, name, is used to specify the name of the server-side named pipe. The second one, flags, allows you to set The last and final one, backlog, specifies the size of the server backlog. Server backlog is defined as the maximum length of the queue of pending client-side connections, i.e. connections which has not been accepted via accept method yet.

Returns true on success. If the named pipe server could not be opened, IO error supplied by operating system is set and then the function returns false [1].

void close()

Closes all previously opened server-side named pipes in the backlog; does nothing if the named pipe server is not started. This function always succeeds.

Sometimes it may be convenient to use disposable pattern to ensure timely invokation of close [2].

io.FileStream* accept(bool isSuspended = false)

Accepts a client connection and returns a resulting io.FileStream object to communicate with this particular client. To terminate a client connection, issue close method on the client file stream object.

If method fails, null value is returned [1].

Aliases

alias dispose = close

Effectively makes io.NamedPipe a disposable class [2].

Footnotes