System.Win32.NamedPipes

Win32-2.14.0.0: A binding to Windows Win32 API.

Safe Haskell | Safe-Inferred
Language | Haskell2010

System.Win32.NamedPipes

Contents

- Named pipe server APIs
  - Parameter types
- Named pipe client APIs
  - connect to a named pipe
  - waiting for named pipe instances

Description

For full details on the Windows named pipes API see https://docs.microsoft.com/en-us/windows/desktop/ipc/named-pipes

Synopsis

- createNamedPipe :: String -> OpenMode -> PipeMode -> DWORD -> DWORD -> DWORD -> DWORD -> Maybe LPSECURITY_ATTRIBUTES -> IO HANDLE
- pIPE_UNLIMITED_INSTANCES :: DWORD
- type LPSECURITY_ATTRIBUTES = Ptr SECURITY_ATTRIBUTES
- type OpenMode = UINT
- pIPE_ACCESS_DUPLEX :: OpenMode
- pIPE_ACCESS_INBOUND :: OpenMode
- pIPE_ACCESS_OUTBOUND :: OpenMode
- fILE_FLAG_OVERLAPPED :: FileAttributeOrFlag
- type PipeMode = UINT
- pIPE_TYPE_BYTE :: PipeMode
- pIPE_TYPE_MESSAGE :: PipeMode
- pIPE_READMODE_BYTE :: PipeMode
- pIPE_READMODE_MESSAGE :: PipeMode
- pIPE_WAIT :: PipeMode
- pIPE_NOWAIT :: PipeMode
- pIPE_ACCEPT_REMOTE_CLIENTS :: PipeMode
- pIPE_REJECT_REMOTE_CLIENTS :: PipeMode
- connect :: String -> AccessMode -> ShareMode -> Maybe LPSECURITY_ATTRIBUTES -> CreateMode -> FileAttributeOrFlag -> Maybe HANDLE -> IO HANDLE
- waitNamedPipe :: String -> TimeOut -> IO Bool
- type TimeOut = DWORD
- nMPWAIT_USE_DEFAULT_WAIT :: TimeOut
- nMPWAIT_WAIT_FOREVER :: TimeOut

# Named pipe server APIs

createNamedPipe Source #

Arguments

:: String | A unique pipe name of the form `\.pipe{pipename}` The `pipename` part of the name can include any character other than a backslash, including numbers and special characters. The entire pipe name string can be up to 256 characters long. Pipe names are not case sensitive.
-> OpenMode |
-> PipeMode |
-> DWORD | nMaxInstances
-> DWORD | nOutBufferSize
-> DWORD | nInBufferSize
-> DWORD | nDefaultTimeOut
-> Maybe LPSECURITY_ATTRIBUTES |
-> IO HANDLE |

Creates an instance of a named pipe and returns a handle for subsequent pipe operations. A named pipe server process uses this function either to create the first instance of a specific named pipe and establish its basic attributes or to create a new instance of an existing named pipe.

For full details see https://docs.microsoft.com/en-us/windows/desktop/api/winbase/nf-winbase-createnamedpipea

To create a named pipe which can be associate with IO completion port on needs to pass `fILE_FLAG_OVERLAPPED` to `OpenMode` argument, e.g.

     Win32.createNamedPipe pipeName
                           (pIPE_ACCESS_DUPLEX .|. fILE_FLAG_OVERLAPPED)
                           (pIPE_TYPE_BYTE .|. pIPE_READMODE_BYTE)
                           pIPE_UNLIMITED_INSTANCES
                           512
                           512
                           0
                           NothinROR

pIPE_UNLIMITED_INSTANCES :: DWORD Source #

## Parameter types

type LPSECURITY_ATTRIBUTES = Ptr SECURITY_ATTRIBUTES Source #

type OpenMode = UINT Source #

The named pipe open mode.

This must specify one of:

- `pIPE_ACCESS_DUPLEX`
- `pIPE_ACCESS_INBOUND`
- `pIPE_ACCESS_OUTBOUND`

It may also specify:

- `fILE_FLAG_WRITE_THROUGH`
- `fILE_FLAG_OVERLAPPED`

It may also specify any combination of:

- `wRITE_DAC`
- `wRITE_OWNER`
- `aCCESS_SYSTEM_SECURITY`

pIPE_ACCESS_DUPLEX :: OpenMode Source #

pIPE_ACCESS_INBOUND :: OpenMode Source #

pIPE_ACCESS_OUTBOUND :: OpenMode Source #

fILE_FLAG_OVERLAPPED :: FileAttributeOrFlag Source #

type PipeMode = UINT Source #

The pipe mode.

One of the following type modes can be specified. The same type mode must be specified for each instance of the pipe.

- `pIPE_TYPE_BYTE`
- `pIPE_TYPE_MESSAGE`

One of the following read modes can be specified. Different instances of the same pipe can specify different read modes.

- `pIPE_READMODE_BYTE`
- `pIPE_READMODE_MESSAGE`

One of the following wait modes can be specified. Different instances of the same pipe can specify different wait modes.

- `pIPE_WAIT`
- `pIPE_NOWAIT`

One of the following remote-client modes can be specified. Different instances of the same pipe can specify different remote-client modes.

- `pIPE_ACCEPT_REMOTE_CLIENT`
- `pIPE_REJECT_REMOTE_CLIENT`

pIPE_TYPE_BYTE :: PipeMode Source #

pIPE_TYPE_MESSAGE :: PipeMode Source #

pIPE_READMODE_BYTE :: PipeMode Source #

pIPE_READMODE_MESSAGE :: PipeMode Source #

pIPE_WAIT :: PipeMode Source #

pIPE_NOWAIT :: PipeMode Source #

pIPE_ACCEPT_REMOTE_CLIENTS :: PipeMode Source #

If the `createNamedPipe` `nMaxInstances` parameter is `pIPE_UNLIMITED_INSTANCES`, the number of pipe instances that can be created is limited only by the availability of system resources.

pIPE_REJECT_REMOTE_CLIENTS :: PipeMode Source #

# Named pipe client APIs

## connect to a named pipe

connect Source #

Arguments

:: String | file name
-> AccessMode | dwDesiredAccess
-> ShareMode | dwSharedMode
-> Maybe LPSECURITY_ATTRIBUTES | lpSecurityAttributes
-> CreateMode | dwCreationDisposition
-> FileAttributeOrFlag | dwFlagsAndAttributes
-> Maybe HANDLE | hTemplateFile
-> IO HANDLE |

A reliable connect call, as designed in https://docs.microsoft.com/en-us/windows/win32/ipc/named-pipe-client

The arguments are passed directly to `createFile`.

Note we pick the more familiar posix naming convention, do not confuse this function with `connectNamedPipe` (which corresponds to posix `accept`)

## waiting for named pipe instances

waitNamedPipe Source #

Arguments

:: String | pipe name
-> TimeOut | nTimeOut
-> IO Bool |

Wait until a named pipe instance is available. If there is no instance at hand before the timeout, it will error with `ERROR_SEM_TIMEOUT`, i.e. `invalid argument (The semaphore timeout period has expired)`

It returns `True` if there is an available instance, subsequent `createFile` might still fail, if another thread will take turn and connect before, or if the other end shuts down the name pipe.

It returns `False` if timeout fired.

type TimeOut = DWORD Source #

Timeout in milliseconds.

- `nMPWAIT_USE_DEFAULT_WAIT` indicates that the timeout value passed to `createNamedPipe` should be used.
- `nMPWAIT_WAIT_FOREVER` - `waitNamedPipe` will block forever, until a named pipe instance is available.

nMPWAIT_USE_DEFAULT_WAIT :: TimeOut Source #

nMPWAIT_WAIT_FOREVER :: TimeOut Source #