1//
2// Pipe.h
3//
4// Library: Foundation
5// Package: Processes
6// Module: Pipe
7//
8// Definition of the Pipe class.
9//
10// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
11// and Contributors.
12//
13// SPDX-License-Identifier: BSL-1.0
14//
15
16
17#ifndef Foundation_Pipe_INCLUDED
18#define Foundation_Pipe_INCLUDED
19
20
21#include "Poco/Foundation.h"
22#include "Poco/PipeImpl.h"
23
24
25namespace Poco {
26
27
28class Foundation_API Pipe
29 /// This class implements an anonymous pipe.
30 ///
31 /// Pipes are a common method of inter-process communication -
32 /// on Unix, pipes are the oldest form of IPC.
33 ///
34 /// A pipe is a half-duplex communication channel, which means
35 /// that data only flows in one direction.
36 /// Pipes have a read-end and a write-end. One process writes to
37 /// the pipe and another process reads the data written by
38 /// its peer.
39 /// Read and write operations are always synchronous. A read will
40 /// block until data is available and a write will block until
41 /// the reader reads the data.
42 ///
43 /// The sendBytes() and readBytes() methods of Pipe are usually
44 /// used through a PipeOutputStream or PipeInputStream and are
45 /// not called directly.
46 ///
47 /// Pipe objects have value semantics; the actual work is delegated
48 /// to a reference-counted PipeImpl object.
49{
50public:
51 typedef PipeImpl::Handle Handle; /// The read/write handle or file descriptor.
52
53 enum CloseMode /// used by close()
54 {
55 CLOSE_READ = 0x01, /// Close reading end of pipe.
56 CLOSE_WRITE = 0x02, /// Close writing end of pipe.
57 CLOSE_BOTH = 0x03 /// Close both ends of pipe.
58 };
59
60 Pipe();
61 /// Creates the Pipe.
62 ///
63 /// Throws a CreateFileException if the pipe cannot be
64 /// created.
65
66 Pipe(const Pipe& pipe);
67 /// Creates the Pipe using the PipeImpl from another one.
68
69 ~Pipe();
70 /// Closes and destroys the Pipe.
71
72 Pipe& operator = (const Pipe& pipe);
73 /// Releases the Pipe's PipeImpl and assigns another one.
74
75 int writeBytes(const void* buffer, int length);
76 /// Sends the contents of the given buffer through
77 /// the pipe. Blocks until the receiver is ready
78 /// to read the data.
79 ///
80 /// Returns the number of bytes sent.
81 ///
82 /// Throws a WriteFileException if the data cannot be written.
83
84 int readBytes(void* buffer, int length);
85 /// Receives data from the pipe and stores it
86 /// in buffer. Up to length bytes are received.
87 /// Blocks until data becomes available.
88 ///
89 /// Returns the number of bytes received, or 0
90 /// if the pipe has been closed.
91 ///
92 /// Throws a ReadFileException if nothing can be read.
93
94 Handle readHandle() const;
95 /// Returns the read handle or file descriptor
96 /// for the Pipe. For internal use only.
97
98 Handle writeHandle() const;
99 /// Returns the write handle or file descriptor
100 /// for the Pipe. For internal use only.
101
102 void close(CloseMode mode = CLOSE_BOTH);
103 /// Depending on the argument, closes either the
104 /// reading end, the writing end, or both ends
105 /// of the Pipe.
106
107private:
108 PipeImpl* _pImpl;
109};
110
111
112//
113// inlines
114//
115inline int Pipe::writeBytes(const void* buffer, int length)
116{
117 return _pImpl->writeBytes(buffer, length);
118}
119
120
121inline int Pipe::readBytes(void* buffer, int length)
122{
123 return _pImpl->readBytes(buffer, length);
124}
125
126
127inline Pipe::Handle Pipe::readHandle() const
128{
129 return _pImpl->readHandle();
130}
131
132
133inline Pipe::Handle Pipe::writeHandle() const
134{
135 return _pImpl->writeHandle();
136}
137
138
139} // namespace Poco
140
141
142#endif // Foundation_Pipe_INCLUDED
143