dep/ACE_wrappers/ace/SPIPE_Acceptor.h

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