ChangeLogTag:Tue Dec 18 11:11:29 2001 Steve Huston <shuston@riverace.com>

1 files changed, 34 insertions, 5 deletions

diff --git a/ace/SPIPE.h b/ace/SPIPE.h
index 5b49146ea34..04e06d71011 100644
--- a/ace/SPIPE.h
+++ b/ace/SPIPE.h
@@ -28,24 +28,53 @@
  *
  * @brief Defines the member functions for the base class of the
  * ACE_SPIPE abstraction.
+ *
+ * ACE_SPIPE was designed as a wrapper facade for STREAM pipes. On
+ * Windows, however, ACE_SPIPE is a wrapper for Named Pipes. Therefore,
+ * on Windows, it is better to use the ACE_Proactor or blocking operations
+ * in lieu of using the ACE_Reactor.
+ *
+ * @sa ACE_SPIPE_Acceptor for additional notes on use with ACE_Reactor
+ * on Windows.
+ *
+ * @warning Windows: Works only on Windows NT 4 and higher.
+ * @warning Works on non-Windows platforms only when @c ACE_HAS_STREAM_PIPES
+ * is defined.
  */
 class ACE_Export ACE_SPIPE : public ACE_IPC_SAP
 {
 public:
-  /// Close down the STREAM pipe without removing the rendezvous point.
+  /// Close down the SPIPE without removing the rendezvous point.
+  /**
+   * Closes the underlying pipe handle and sets this object's handle value
+   * to @c ACE_INVALID_HANDLE.
+   * @return 0 for success; -1 for failure. If a failure occurs, further
+   * error information is available from ACE_OS::last_error().
+   */
   int close (void);
 
-  /// Close down the STREAM pipe and remove the rendezvous point from
+  /// Close down the SPIPE and remove the rendezvous point from
   /// the file system.
+  /**
+   * @return 0 for success; -1 for failure. If a failure occurs, further
+   * error information is available from ACE_OS::last_error().
+   */
   int remove (void);
 
   /// Return the local address of this endpoint.
+  /**
+   * Returns the local address of the SPIPE's endpoint in @arg addr.
+   * @return 0 for success; -1 for failure. If a failure occurs, further
+   * error information is available from ACE_OS::last_error().
+   */
   int get_local_addr (ACE_SPIPE_Addr &) const;
 
   /**
-   * Disable signal <signum>
-   * This is here to prevent Win32 from
-   * disabling SPIPE using socket calls
+   * Disable signal @arg signum.
+   * @note This reimplements the inherited method from
+   * ACE_IPC_SAP. Since the signal actions do not make any sense on
+   * Windows, this method intercepts the call and NOPs it. On non-Windows,
+   * it is passed through to ACE_IPC_SAP::disable().
    */
   int disable (int signum) const ;