ACE/ace/SPIPE_Acceptor.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    SPIPE_Acceptor.h
   6  *
   7  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
   8  *  @author Prashant Jain <pjain@cs.wustl.edu>
   9  */
  10 //=============================================================================
  11
  12
  13 #ifndef ACE_SPIPE_ACCEPTOR_H
  14 #define ACE_SPIPE_ACCEPTOR_H
  15 #include /**/ "ace/pre.h"
  16
  17 #include "ace/SPIPE_Stream.h"
  18
  19 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  20 # pragma once
  21 #endif /* ACE_LACKS_PRAGMA_ONCE */
  22
  23 #if defined (ACE_HAS_WIN32_NAMED_PIPES)
  24 #include "ace/Manual_Event.h"
  25 #endif /* ACE_HAS_WIN32_NAMED_PIPES */
  26
  27 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  28
  29 /**
  30  * @class ACE_SPIPE_Acceptor
  31  *
  32  * @brief A factory class that produces ACE_SPIPE_Stream objects.
  33  *
  34  * ACE_SPIPE_Acceptor is a factory class that accepts SPIPE connections.
  35  * Each accepted connection produces an ACE_SPIPE_Stream object.
  36  *
  37  * @warning Windows: Works only on Windows NT 4 and higher. To use this
  38  * class with the ACE_Reactor framework, note that the handle to
  39  * demultiplex on is an event handle and should be registered with the
  40  * ACE_Reactor::register_handler (ACE_Event_Handler *, ACE_HANDLE) method.
  41  *
  42  * @warning Works on non-Windows platforms only when @c ACE_HAS_STREAM_PIPES
  43  * is defined.
  44  */
  45 class ACE_Export ACE_SPIPE_Acceptor : public ACE_SPIPE
  46 {
  47 public:
  48   /// Default constructor.
  49   ACE_SPIPE_Acceptor (void);
  50
  51   /// Initiate a passive-mode STREAM pipe listener.
  52   /**
  53    * @param local_sap   The name of the pipe instance to open and listen on.
  54    * @param reuse_addr  Optional, and ignored. Needed for API compatibility
  55    *                    with other acceptor classes.
  56    * @param perms       Optional, the protection mask to create the pipe
  57    *                    with. Ignored on Windows.
  58    * @param sa          Optional, ignored on non-Windows. The
  59    *                    SECURITY_ATTRIBUTES to create the named pipe
  60    *                    instances with. This pointer is remembered and
  61    *                    reused on each new named pipe instance, so only
  62    *                    pass a value that remains valid as long as this
  63    *                    object does.
  64    * @param pipe_mode   Optional, ignored on non-Windows. The NT pipe
  65    *                    mode used when creating the pipe.
  66    */
  67   ACE_SPIPE_Acceptor (const ACE_SPIPE_Addr &local_sap,
  68                       int reuse_addr = 1,
  69                       int perms = ACE_DEFAULT_FILE_PERMS,
  70                       LPSECURITY_ATTRIBUTES sa = 0,
  71                       int pipe_mode = PIPE_TYPE_MESSAGE | PIPE_READMODE_MESSAGE);
  72
  73   /// Initiate a passive-mode STREAM pipe listener.
  74   /**
  75    * @param local_sap   The name of the pipe instance to open and listen on.
  76    * @param reuse_addr  Optional, and ignored. Needed for API compatibility
  77    *                    with other acceptor classes.
  78    * @param perms       Optional, the protection mask to create the pipe
  79    *                    with. Ignored on Windows.
  80    * @param sa          Optional, ignored on non-Windows. The
  81    *                    SECURITY_ATTRIBUTES to create the named pipe
  82    *                    instances with. This pointer is remembered and
  83    *                    reused on each new named pipe instance, so only
  84    *                    pass a value that remains valid as long as this
  85    *                    object does.
  86    * @param pipe_mode   Optional, ignored on non-Windows. The NT pipe
  87    *                    mode used when creating the pipe.
  88    *
  89    * @retval 0 for success.
  90    * @retval -1 for failure.
  91    */
  92   int open (const ACE_SPIPE_Addr &local_sap,
  93             int reuse_addr = 1,
  94             int perms = ACE_DEFAULT_FILE_PERMS,
  95             LPSECURITY_ATTRIBUTES sa = 0,
  96             int pipe_mode = PIPE_TYPE_MESSAGE | PIPE_READMODE_MESSAGE);
  97
  98   /// Close down the passive-mode STREAM pipe listener.
  99   int close (void);
 100
 101   /// Remove the underlying mounted pipe from the file system.
 102   int remove (void);
 103
 104   // = Passive connection acceptance method.
 105   /**
 106    * Accept a new data transfer connection.
 107    *
 108    * @param ipc_sap_spipe  The ACE_SPIPE_Stream to initialize with the
 109    *                       newly-accepted pipe.
 110    * @param remote_addr    Optional, accepts the address of the peer.
 111    * @param timeout        0 means block forever, {0, 0} means poll.
 112    * @param restart        1 means "restart if interrupted."
 113    *
 114    * @retval 0 for success.
 115    * @retval -1 for failure.
 116    */
 117   int accept (ACE_SPIPE_Stream &ipc_sap_spipe,
 118               ACE_SPIPE_Addr *remote_addr = 0,
 119               ACE_Time_Value *timeout = 0,
 120               bool restart = true,
 121               bool reset_new_handle = false);
 122
 123   // = Meta-type info
 124   typedef ACE_SPIPE_Addr PEER_ADDR;
 125   typedef ACE_SPIPE_Stream PEER_STREAM;
 126
 127   /// Dump the state of an object.
 128   void dump (void) const;
 129
 130   /// Declare the dynamic allocation hooks.
 131   ACE_ALLOC_HOOK_DECLARE;
 132
 133 private:
 134   /// Create a new instance of an SPIPE.
 135   int create_new_instance (int perms = 0);
 136
 137 #if defined (ACE_HAS_WIN32_NAMED_PIPES)
 138   // On Windows, the SECURITY_ATTRIBUTES specified for the initial accept
 139   // operation is reused on all subsequent pipe instances as well.
 140   LPSECURITY_ATTRIBUTES sa_;
 141
 142   // On Windows, the pipe mode to create the pipe in.  This can be in
 143   // either a bytestream-oriented mode or a message-oriented mode.
 144   DWORD pipe_mode_;
 145
 146   // On Windows, the handle maintained in the ACE_IPC_SAP class is the
 147   // event handle from event. The pipe handle is useless for telling
 148   // when a pipe connect is done/ready, and it changes on each pipe
 149   // acceptance, quite unlike other acceptor-type classes in ACE.
 150   // This allows the get_handle()-obtained handle to be used for
 151   // registering with the reactor (albeit for signal, not input)
 152   // to tell when a pipe accept is done.
 153   ACE_OVERLAPPED   overlapped_;
 154   ACE_Manual_Event event_;
 155   ACE_HANDLE       pipe_handle_;
 156   int              already_connected_;
 157 #endif /* ACE_HAS_WIN32_NAMED_PIPES */
 158
 159 };
 160
 161 ACE_END_VERSIONED_NAMESPACE_DECL
 162
 163 #include /**/ "ace/post.h"
 164 #endif /* ACE_SPIPE_ACCEPTOR_H */