home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _160f7c5f7ff876aa8ac575c2d279873e < prev    next >
Text File  |  2000-03-23  |  11KB  |  265 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>POE::Wheel::SocketFactory - POE Socket Creation Logic Abstraction</TITLE>
  5. <LINK REL="stylesheet" HREF="../../../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> POE::Wheel::SocketFactory - POE Socket Creation Logic Abstraction</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <LI><A HREF="#public methods">PUBLIC METHODS</A></LI>
  26.     <LI><A HREF="#events and parameters">EVENTS AND PARAMETERS</A></LI>
  27.     <LI><A HREF="#see also">SEE ALSO</A></LI>
  28.     <LI><A HREF="#bugs">BUGS</A></LI>
  29.     <LI><A HREF="#authors & copyrights">AUTHORS & COPYRIGHTS</A></LI>
  30. </UL>
  31. <!-- INDEX END -->
  32.  
  33. <HR>
  34. <P>
  35. <H1><A NAME="name">NAME</A></H1>
  36. <P>POE::Wheel::SocketFactory - POE Socket Creation Logic Abstraction</P>
  37. <P>
  38. <HR>
  39. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  40. <UL>
  41. <LI>Linux</LI>
  42. <LI>Solaris</LI>
  43. <LI>Windows</LI>
  44. </UL>
  45. <HR>
  46. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  47. <PRE>
  48.   use Socket; # For the constants</PRE>
  49. <PRE>
  50.   # Listening Unix domain socket.
  51.   $wheel = new POE::Wheel::SocketFactory(
  52.     SocketDomain => AF_UNIX,               # Sets the socket() domain
  53.     BindAddress  => $unix_socket_address,  # Sets the bind() address
  54.     SuccessState => $success_state,        # State to call upon accept()
  55.     FailureState => $state_failure,        # State to call upon error
  56.     # Optional parameters (and default values):
  57.     SocketType   => SOCK_STREAM,           # Sets the socket() type
  58.   );</PRE>
  59. <PRE>
  60.   # Connecting Unix domain socket.
  61.   $wheel = new POE::Wheel::SocketFactory(
  62.     SocketDomain  => AF_UNIX,              # Sets the socket() domain
  63.     RemoteAddress => $unix_server_address, # Sets the connect() address
  64.     SuccessState  => $success_state,       # State to call on connection
  65.     FailureState  => $state_failure,       # State to call on error
  66.     # Optional parameters (and default values):
  67.     SocketType    => SOCK_STREAM,          # Sets the socket() type
  68.     # Optional parameters (that have no defaults):
  69.     BindAddress   => $unix_client_address, # Sets the bind() address
  70.   );</PRE>
  71. <PRE>
  72.   # Listening Internet domain socket.
  73.   $wheel = new POE::Wheel::SocketFactory(
  74.     BindAddress    => $inet_address,       # Sets the bind() address
  75.     BindPort       => $inet_port,          # Sets the bind() port
  76.     SuccessState   => $success_state,      # State to call upon accept()
  77.     FailureState   => $state_failure,      # State to call upon error
  78.     # Optional parameters (and default values):
  79.     SocketDomain   => AF_INET,             # Sets the socket() domain
  80.     SocketType     => SOCK_STREAM,         # Sets the socket() type
  81.     SocketProtocol => 'tcp',               # Sets the socket() protocol
  82.     ListenQueue    => SOMAXCONN,           # The listen() queue length
  83.     Reuse          => 'no',                # Lets the port be reused
  84.   );</PRE>
  85. <PRE>
  86.   # Connecting Internet domain socket.
  87.   $wheel = new POE::Wheel::SocketFactory(
  88.     RemoteAddress  => $inet_address,       # Sets the connect() address
  89.     RemotePort     => $inet_port,          # Sets the connect() port
  90.     SuccessState   => $success_state,      # State to call on connection
  91.     FailureState   => $state_failure,      # State to call on error
  92.     # Optional parameters (and default values):
  93.     SocketDomain   => AF_INET,             # Sets the socket() domain
  94.     SocketType     => SOCK_STREAM,         # Sets the socket() type
  95.     SocketProtocol => 'tcp',               # Sets the socket() protocol
  96.     Reuse          => 'no',                # Lets the port be reused
  97.   );</PRE>
  98. <PRE>
  99.   $wheel->event( ... );</PRE>
  100. <P>
  101. <HR>
  102. <H1><A NAME="description">DESCRIPTION</A></H1>
  103. <P>This wheel creates sockets, generating events when something happens
  104. to them.  Success events come with connected, ready to use sockets.
  105. Failure events are accompanied by error codes, similar to other
  106. wheels'.</P>
  107. <P>SocketFactory currently supports Unix domain sockets, and TCP sockets
  108. within the Internet domain.  Other protocols are forthcoming,
  109. eventually; let the author or mailing list know if they're needed
  110. sooner.</P>
  111. <P>
  112. <HR>
  113. <H1><A NAME="public methods">PUBLIC METHODS</A></H1>
  114. <UL>
  115. <LI>
  116. POE::Wheel::SocketFactory::new()
  117. <P>The <CODE>new()</CODE> method does most of the work.  It has parameters for just
  118. about every aspect of socket creation: socket(), setsockopt(), bind(),
  119. listen(), <A HREF="../../../../lib/Pod/perlfunc.html#item_connect"><CODE>connect()</CODE></A> and accept().  Thankfully they all aren't used at
  120. the same time.</P>
  121. <P>The parameters:</P>
  122. <UL>
  123. <LI>
  124. SocketDomain
  125. <P>SocketDomain is the DOMAIN parameter for the <A HREF="../../../../lib/Pod/perlfunc.html#item_socket"><CODE>socket()</CODE></A> call.  Currently
  126. supported values are AF_UNIX, AF_INET, PF_UNIX and PF_INET.  It
  127. defaults to AF_INET if omitted.</P>
  128. <P></P>
  129. <LI>
  130. SocketType
  131. <P>SocketType is the TYPE parameter for the <A HREF="../../../../lib/Pod/perlfunc.html#item_socket"><CODE>socket()</CODE></A> call.  Currently
  132. supported values are SOCK_STREAM and SOCK_DGRAM (although datagram
  133. sockets aren't tested at this time).  It defaults to SOCK_STREAM if
  134. omitted.</P>
  135. <P></P>
  136. <LI>
  137. SocketProtocol
  138. <P>SocketProtocol is the PROTOCOL parameter for the <A HREF="../../../../lib/Pod/perlfunc.html#item_socket"><CODE>socket()</CODE></A> call.
  139. Protocols may be specified by name or number (see /etc/protocols, or
  140. the equivalent file).  The only supported protocol at this time is
  141. 'tcp'.  SocketProtocol is ignored for Unix domain sockets.  It
  142. defaults to 'tcp' if omitted from an Internet socket constructor.</P>
  143. <P></P>
  144. <LI>
  145. BindAddress
  146. <P>BindAddress is the local interface address that the socket will be
  147. bound to.</P>
  148. <P>For Internet domain sockets: The bind address may be a string
  149. containing a dotted quad, a host name, or a packed Internet address
  150. (without the port).  It defaults to INADDR_ANY if it's not specified,
  151. which will try to bind the socket to every interface.  If any
  152. interface has a socket already bound to the BindPort, then <A HREF="../../../../lib/Pod/perlfunc.html#item_bind"><CODE>bind()</CODE></A> (and
  153. the SocketFactory) will fail.</P>
  154. <P>For Unix domain sockets: The bind address is a path where the socket
  155. will be created.  It is required for server sockets and datagram
  156. client sockets.  If a file exists at the bind address, then <A HREF="../../../../lib/Pod/perlfunc.html#item_bind"><CODE>bind()</CODE></A>
  157. (and the SocketFactory) will fail.</P>
  158. <P></P>
  159. <LI>
  160. BindPort
  161. <P>BindPort is the port of the local <CODE>interface(s)</CODE> that the socket will
  162. try to bind to.  It is ignored for Unix sockets and recommended for
  163. Internet sockets.  It defaults to 0 if omitted, which will bind the
  164. socket to an unspecified available port.</P>
  165. <P>The bind port may be a number, or a name in the /etc/services (or
  166. equivalent) database.</P>
  167. <P></P>
  168. <LI>
  169. ListenQueue
  170. <P>ListenQueue specifies the length of the socket's <A HREF="../../../../lib/Pod/perlfunc.html#item_listen"><CODE>listen()</CODE></A> queue.  It
  171. defaults to SOMAXCONN if omitted.  SocketFactory will ensure that
  172. ListenQueue doesn't exceed SOMAXCONN.</P>
  173. <P>It should go without saying that ListenQueue is only appropriate for
  174. listening sockets.</P>
  175. <P></P>
  176. <LI>
  177. RemoteAddress
  178. <P>RemoteAddress is the remote address to which the socket should
  179. connect.  If present, the SocketFactory will create a connecting
  180. socket; otherwise, the SocketFactory will make a listening socket.</P>
  181. <P>The remote address may be a string containing a dotted quad, a host
  182. name, a packed Internet address, or a Unix socket path.  It will be
  183. packed, with or without an accompanying RemotePort as necessary for
  184. the socket domain.</P>
  185. <P></P>
  186. <LI>
  187. RemotePort
  188. <P>RemotePort is the port to which the socket should connect.  It is
  189. required for connecting Internet sockets and ignored in all other
  190. cases.</P>
  191. <P>The remote port may be a number, or a name in the /etc/services (or
  192. equivalent) database.</P>
  193. <P></P></UL>
  194. <LI>
  195. POE::Wheel::SocketFactory::event(...)
  196. <P>Please see POE::Wheel.</P>
  197. <P></P>
  198. <LI>
  199. POE::Wheel::SocketFactory::getsockname()
  200. <P>Returns the value of <A HREF="../../../../lib/Pod/perlfunc.html#item_getsockname"><CODE>getsockname()</CODE></A> as called with the SocketFactory's
  201. socket.</P>
  202. <P>This is useful for finding out what the SocketFactory's internal
  203. socket has bound to when it's been instructed to use BindAddress =>
  204. INADDR_ANY and/or BindPort => INADDR_ANY.</P>
  205. <P></P></UL>
  206. <P>
  207. <HR>
  208. <H1><A NAME="events and parameters">EVENTS AND PARAMETERS</A></H1>
  209. <UL>
  210. <LI>
  211. SuccessState
  212. <P>The SuccessState parameter defines a state name or coderef to call
  213. upon a successful connect or accept.  The operation it succeeds on
  214. depends on the type of socket created.</P>
  215. <P>For connecting sockets, the success state/coderef is called when the
  216. socket has connected.  For listening sockets, the success
  217. state/coderef is called for each successfully accepted client
  218. connection.</P>
  219. <P>ARG0 contains the connected or accepted socket.</P>
  220. <P>For INET sockets, ARG1 and ARG2 hold the socket's remote address and
  221. port, respectively.</P>
  222. <P>For Unix client sockets, ARG1 contains the server address and ARG2 is
  223. undefined.</P>
  224. <P>According to _Perl Cookbook_, the remote address for accepted Unix
  225. domain sockets is undefined.  So ARG0 and ARG1 are, too.</P>
  226. <P></P>
  227. <LI>
  228. FailureState
  229. <P>The FailureState parameter defines a state name or coderef to call
  230. when a socket error occurs.  The SocketFactory knows what to do with
  231. EAGAIN, so that's not considered an error.</P>
  232. <P>The ARG0 parameter contains the name of the function that failed.
  233. ARG1 and ARG2 contain the numeric and string versions of $! at the
  234. time of the error, respectively.</P>
  235. <P>A sample ErrorState state:</P>
  236. <PRE>
  237.   sub error_state {
  238.     my ($operation, $errnum, $errstr) = @_[ARG0, ARG1, ARG2];
  239.     warn "$operation error $errnum: $errstr\n";
  240.   }</PRE>
  241. <P></P></UL>
  242. <P>
  243. <HR>
  244. <H1><A NAME="see also">SEE ALSO</A></H1>
  245. <P>POE::Wheel; POE::Wheel::FollowTail; POE::Wheel::ListenAccept;
  246. POE::Wheel::ReadWrite; POE::Wheel::SocketFactory</P>
  247. <P>
  248. <HR>
  249. <H1><A NAME="bugs">BUGS</A></H1>
  250. <P>Many (if not all) of the croak/carp/warn/die statements should fire
  251. back $state_failure instead.</P>
  252. <P>
  253. <HR>
  254. <H1><A NAME="authors & copyrights">AUTHORS & COPYRIGHTS</A></H1>
  255. <P>Please see the POE manpage.</P>
  256. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  257. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  258. <STRONG><P CLASS=block> POE::Wheel::SocketFactory - POE Socket Creation Logic Abstraction</P></STRONG>
  259. </TD></TR>
  260. </TABLE>
  261.  
  262. </BODY>
  263.  
  264. </HTML>
  265.