1 kumpf 1.1 //%2003////////////////////////////////////////////////////////////////////////
  2           //
  3           // Copyright (c) 2000, 2001, 2002  BMC Software, Hewlett-Packard Development
  4           // Company, L. P., IBM Corp., The Open Group, Tivoli Systems.
  5           // Copyright (c) 2003 BMC Software; Hewlett-Packard Development Company, L. P.;
  6           // IBM Corp.; EMC Corporation, The Open Group.
  7           //
  8           // Permission is hereby granted, free of charge, to any person obtaining a copy
  9           // of this software and associated documentation files (the "Software"), to
 10           // deal in the Software without restriction, including without limitation the
 11           // rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 12           // sell copies of the Software, and to permit persons to whom the Software is
 13           // furnished to do so, subject to the following conditions:
 14           // 
 15           // THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
 16           // ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
 17           // "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
 18           // LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
 19           // PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 20           // HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
 21           // ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 22 kumpf 1.1 // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 23           //
 24           //==============================================================================
 25           //
 26           // Author: Carol Ann Krug Graves, Hewlett-Packard Company
 27           //             (carolann_graves@hp.com)
 28           //
 29           // Modified By: 
 30           //
 31           //%/////////////////////////////////////////////////////////////////////////////
 32           
 33           #ifndef Pegasus_AnonymousPipe_h
 34           #define Pegasus_AnonymousPipe_h
 35           
 36           #include <Pegasus/Common/Config.h>
 37           #include <Pegasus/Common/Linkage.h>
 38           #include <Pegasus/Common/String.h>
 39           #include <Pegasus/Common/CIMMessage.h>
 40           
 41           
 42           PEGASUS_NAMESPACE_BEGIN
 43 kumpf 1.1 
 44           /** 
 45               The AnonymousPipe class implements an anonymous pipe.
 46           
 47               @author  Hewlett-Packard Company
 48           
 49           */
 50           class PEGASUS_COMMON_LINKAGE AnonymousPipe
 51           {
 52           public:
 53               /**
 54                   Constructs an AnonymousPipe instance.
 55           
 56                   @throw   Exception (Failed to create pipe)
 57               */
 58               AnonymousPipe ();
 59           
 60               /**
 61                   Constructs an AnonymousPipe instance, given the read and/or write handle
 62                   in char form.
 63           
 64 kumpf 1.1         NOTE: before using this form of the constructor, the pipe must already 
 65                   exist (a previous invocation of the AnonymousPipe () form of the 
 66                   constructor), and the specified handle(s) should be open for the 
 67                   specified operation (read or write).  The read or write handle 
 68                   should be obtained via a call to exportReadHandle () or 
 69                   exportWriteHandle (), respectively.
 70           
 71                   @param   readHandle       char [] representation of the read handle to 
 72                                               the pipe
 73                   @param   writeHandle      char [] representation of the write handle to
 74                                               the pipe
 75           
 76                   @throw   Exception (Failed to create pipe)
 77               */
 78               AnonymousPipe (
 79                   const char * readHandle,
 80                   const char * writeHandle);
 81           
 82               /**
 83                   Destructs the AnonymousPipe instance.
 84           
 85 kumpf 1.1         Closes the open pipe handles.
 86               */
 87               ~AnonymousPipe ();
 88           
 89               /**
 90                   Defines symbolic constants for return values from read and write
 91                   methods.
 92               */
 93               enum Status {STATUS_INTERRUPT = -2, 
 94                            STATUS_ERROR     = -1, 
 95                            STATUS_CLOSED    =  0, 
 96                            STATUS_SUCCESS   =  1};
 97           
 98               /**
 99                   Writes data from a buffer to the AnonymousPipe.  
100           
101                   @param   buffer           pointer to the input data buffer
102                   @param   bytesToWrite     Number of bytes to write
103           
104                   @return  STATUS_SUCCESS   on success; 
105                            STATUS_CLOSED    on closed connection; 
106 kumpf 1.1                  STATUS_ERROR     on error;
107               */
108               Status writeBuffer (
109                   const char * buffer,
110                   Uint32 bytesToWrite);
111           
112               /**
113                   Writes a CIM message to the AnonymousPipe.  
114           
115                   The message is serialized, then written to the pipe.
116           
117                   @param   message          pointer to the message
118           
119                   @return  STATUS_SUCCESS   on success; 
120                            STATUS_CLOSED    on closed connection; 
121                            STATUS_ERROR     on error;
122               */
123               Status writeMessage (
124                   CIMMessage * message);
125           
126               /**
127 kumpf 1.1         Reads data into a buffer from the AnonymousPipe.  
128           
129                   @param   buffer           pointer to the output data buffer
130                   @param   bytesToRead      Number of bytes to read
131           
132                   @return  STATUS_SUCCESS   on success; 
133                            STATUS_CLOSED    on closed connection; 
134                            STATUS_ERROR     on error;
135                            STATUS_INTERRUPT on interrupt
136               */
137               Status readBuffer (
138                   char * buffer,
139                   Uint32 bytesToRead);
140           
141               /**
142                   Reads a CIM message from the AnonymousPipe.  
143           
144                   A message is read from the pipe, then de-serialized.
145           
146                   @param   message          pointer to the message (output parameter)
147           
148 kumpf 1.1         @return  STATUS_SUCCESS   on success; 
149                            STATUS_CLOSED    on closed connection; 
150                            STATUS_ERROR     on error;
151                            STATUS_INTERRUPT on interrupt
152               */
153               Status readMessage (
154               CIMMessage * & message);
155           
156               /**
157                   Gets a char [] form of the pipe handle for reading from the 
158                   AnonymousPipe instance.  
159           
160                   NOTE: the caller must supply the buffer.  The buffer size must be at 
161                         least 32.
162               */
163               void exportReadHandle (
164                   char * buffer) const;
165           
166               /**
167                   Gets a char [] form of the pipe handle for writing to the 
168                   AnonymousPipe instance.  
169 kumpf 1.1 
170                   NOTE: the caller must supply the buffer.  The buffer size must be at 
171                         least 32.
172               */
173               void exportWriteHandle (
174                   char * buffer) const;
175           
176               /**
177                   Closes the pipe handle for reading from the AnonymousPipe instance.  
178               */
179               void closeReadHandle ();
180           
181               /**
182                   Closes the pipe handle for writing to the AnonymousPipe instance.  
183               */
184               void closeWriteHandle ();
185           
186           private:
187           
188               /**
189                   Private, unimplemented copy constructor to avoid implicit use of
190 kumpf 1.1         the default copy constructor
191               */
192               AnonymousPipe (const AnonymousPipe & anonymousPipe) {}
193           
194               /**
195                   Private, unimplemented assignment operator to avoid implicit use of 
196                   the default assignment operator
197               */
198               AnonymousPipe & operator= (const AnonymousPipe & anonymousPipe) 
199                   {return *this;}
200           
201           #if defined (PEGASUS_OS_TYPE_WINDOWS)
202               typedef HANDLE AnonymousPipeHandle;
203           #else
204               typedef int AnonymousPipeHandle;
205           #endif
206           
207               /**
208                   Stores the read pipe handle.
209               */
210               AnonymousPipeHandle _readHandle;
211 kumpf 1.1 
212               /**
213                   Stores the write pipe handle.
214               */
215               AnonymousPipeHandle _writeHandle;
216           
217               /**
218                   Indicates whether the read handle is open.
219               */
220               Boolean _readOpen;
221           
222               /**
223                   Indicates whether the write handle is open.
224               */
225               Boolean _writeOpen;
226           };
227           
228           PEGASUS_NAMESPACE_END
229           
230           #endif /* Pegasus_AnonymousPipe_h */