connect-to-named-pipe

connect-to-named-pipe Function

Summary

Opens a stream connection to a named pipe.

Package

win32

Signature

connect-to-named-pipe name &key host errorp direction => stream, keyword, condition

Arguments

`name`⇩	A string.
`host`⇩	A string or `nil`.
`errorp`⇩	A boolean.
`direction`⇩	One of the keywords `:io`, `:input` and `:output`.

Values

`stream`⇩	A stream or `nil`.
`keyword`⇩	A keyword or `nil`.
`condition`⇩	An error condition or `nil`.

Description

The function connect-to-named-pipe opens a connection to a named pipe and returns a stream connected to it that can be used like any other stream.

name is the pipe name. It can contain any character except #\\ (according to the MSDN). For successful connection another process must have already created a pipe with that name, with the right input/output direction and permissions for the caller of connect-to-named-pipe, and tried to connect to it but has not succeeded yet. In LispWorks this is done by open-named-pipe-stream. The Windows function is ConnectNamedPipe.

host, if non-nil, specifies a host on which the named pipe was created. host nil means the current machine.

direction specifies the direction of input/output. It needs be allowed by the pipe (in inverse, that is if connect-to-named-pipe gets direction :input then the pipe must have been opened for output, for example by calling open-named-pipe-stream with direction :output or :io). The default value of direction is :io.

errorp specifies what to do in case of failure. If it is non-nil (the default), an error is signaled. If it is nil, then connect-to-named-pipe returns stream nil, keyword is a descriptive keyword, and condition is an error condition. keyword can be one of:

`:does-not-exist`	There is no named pipe with this name.
`:all-in-use`	There is at least one named pipe with this name, but all are already connected.
`:access-denied`	There is already a named pipe with this name, but it denies access. That may be either because the permissions of the named pipe do not allow the connection, or because other security features of the host system block the connection.
`:error`	An unknown error.

On success connect-to-named-pipe returns a stream and the other two returned values are both nil.