Chip 2000 May

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 >

Wrap

Text File | 2000-03-23 | 11.0 KB | 265 lines

<HTML> <HEAD> <TITLE>POE::Wheel::SocketFactory - POE Socket Creation Logic Abstraction</TITLE> <LINK REL="stylesheet" HREF="../../../../Active.css" TYPE="text/css"> <LINK REV="made" HREF="mailto:"> </HEAD> <BODY> <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%> <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc"> <STRONG><P CLASS=block> POE::Wheel::SocketFactory - POE Socket Creation Logic Abstraction</P></STRONG> </TD></TR> </TABLE> <A NAME="__index__"></A>  <UL> <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI> <LI><A HREF="#synopsis">SYNOPSIS</A></LI> <LI><A HREF="#description">DESCRIPTION</A></LI> <LI><A HREF="#public methods">PUBLIC METHODS</A></LI> <LI><A HREF="#events and parameters">EVENTS AND PARAMETERS</A></LI> <LI><A HREF="#see also">SEE ALSO</A></LI> <LI><A HREF="#bugs">BUGS</A></LI> <LI><A HREF="#authors & copyrights">AUTHORS & COPYRIGHTS</A></LI> </UL>  <HR> <P> <H1><A NAME="name">NAME</A></H1> <P>POE::Wheel::SocketFactory - POE Socket Creation Logic Abstraction</P> <P> <HR> <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1> <UL> <LI>Linux</LI> <LI>Solaris</LI> <LI>Windows</LI> </UL> <HR> <H1><A NAME="synopsis">SYNOPSIS</A></H1> <PRE> use Socket; # For the constants</PRE> <PRE> # Listening Unix domain socket. $wheel = new POE::Wheel::SocketFactory( SocketDomain => AF_UNIX, # Sets the socket() domain BindAddress => $unix_socket_address, # Sets the bind() address SuccessState => $success_state, # State to call upon accept() FailureState => $state_failure, # State to call upon error # Optional parameters (and default values): SocketType => SOCK_STREAM, # Sets the socket() type );</PRE> <PRE> # Connecting Unix domain socket. $wheel = new POE::Wheel::SocketFactory( SocketDomain => AF_UNIX, # Sets the socket() domain RemoteAddress => $unix_server_address, # Sets the connect() address SuccessState => $success_state, # State to call on connection FailureState => $state_failure, # State to call on error # Optional parameters (and default values): SocketType => SOCK_STREAM, # Sets the socket() type # Optional parameters (that have no defaults): BindAddress => $unix_client_address, # Sets the bind() address );</PRE> <PRE> # Listening Internet domain socket. $wheel = new POE::Wheel::SocketFactory( BindAddress => $inet_address, # Sets the bind() address BindPort => $inet_port, # Sets the bind() port SuccessState => $success_state, # State to call upon accept() FailureState => $state_failure, # State to call upon error # Optional parameters (and default values): SocketDomain => AF_INET, # Sets the socket() domain SocketType => SOCK_STREAM, # Sets the socket() type SocketProtocol => 'tcp', # Sets the socket() protocol ListenQueue => SOMAXCONN, # The listen() queue length Reuse => 'no', # Lets the port be reused );</PRE> <PRE> # Connecting Internet domain socket. $wheel = new POE::Wheel::SocketFactory( RemoteAddress => $inet_address, # Sets the connect() address RemotePort => $inet_port, # Sets the connect() port SuccessState => $success_state, # State to call on connection FailureState => $state_failure, # State to call on error # Optional parameters (and default values): SocketDomain => AF_INET, # Sets the socket() domain SocketType => SOCK_STREAM, # Sets the socket() type SocketProtocol => 'tcp', # Sets the socket() protocol Reuse => 'no', # Lets the port be reused );</PRE> <PRE> $wheel->event( ... );</PRE> <P> <HR> <H1><A NAME="description">DESCRIPTION</A></H1> <P>This wheel creates sockets, generating events when something happens to them. Success events come with connected, ready to use sockets. Failure events are accompanied by error codes, similar to other wheels'.</P> <P>SocketFactory currently supports Unix domain sockets, and TCP sockets within the Internet domain. Other protocols are forthcoming, eventually; let the author or mailing list know if they're needed sooner.</P> <P> <HR> <H1><A NAME="public methods">PUBLIC METHODS</A></H1> <UL> <LI> POE::Wheel::SocketFactory::new() <P>The <CODE>new()</CODE> method does most of the work. It has parameters for just about every aspect of socket creation: socket(), setsockopt(), bind(), listen(), <A HREF="../../../../lib/Pod/perlfunc.html#item_connect"><CODE>connect()</CODE></A> and accept(). Thankfully they all aren't used at the same time.</P> <P>The parameters:</P> <UL> <LI> SocketDomain <P>SocketDomain is the DOMAIN parameter for the <A HREF="../../../../lib/Pod/perlfunc.html#item_socket"><CODE>socket()</CODE></A> call. Currently supported values are AF_UNIX, AF_INET, PF_UNIX and PF_INET. It defaults to AF_INET if omitted.</P> <P></P> <LI> SocketType <P>SocketType is the TYPE parameter for the <A HREF="../../../../lib/Pod/perlfunc.html#item_socket"><CODE>socket()</CODE></A> call. Currently supported values are SOCK_STREAM and SOCK_DGRAM (although datagram sockets aren't tested at this time). It defaults to SOCK_STREAM if omitted.</P> <P></P> <LI> SocketProtocol <P>SocketProtocol is the PROTOCOL parameter for the <A HREF="../../../../lib/Pod/perlfunc.html#item_socket"><CODE>socket()</CODE></A> call. Protocols may be specified by name or number (see /etc/protocols, or the equivalent file). The only supported protocol at this time is 'tcp'. SocketProtocol is ignored for Unix domain sockets. It defaults to 'tcp' if omitted from an Internet socket constructor.</P> <P></P> <LI> BindAddress <P>BindAddress is the local interface address that the socket will be bound to.</P> <P>For Internet domain sockets: The bind address may be a string containing a dotted quad, a host name, or a packed Internet address (without the port). It defaults to INADDR_ANY if it's not specified, which will try to bind the socket to every interface. If any interface has a socket already bound to the BindPort, then <A HREF="../../../../lib/Pod/perlfunc.html#item_bind"><CODE>bind()</CODE></A> (and the SocketFactory) will fail.</P> <P>For Unix domain sockets: The bind address is a path where the socket will be created. It is required for server sockets and datagram client sockets. If a file exists at the bind address, then <A HREF="../../../../lib/Pod/perlfunc.html#item_bind"><CODE>bind()</CODE></A> (and the SocketFactory) will fail.</P> <P></P> <LI> BindPort <P>BindPort is the port of the local <CODE>interface(s)</CODE> that the socket will try to bind to. It is ignored for Unix sockets and recommended for Internet sockets. It defaults to 0 if omitted, which will bind the socket to an unspecified available port.</P> <P>The bind port may be a number, or a name in the /etc/services (or equivalent) database.</P> <P></P> <LI> ListenQueue <P>ListenQueue specifies the length of the socket's <A HREF="../../../../lib/Pod/perlfunc.html#item_listen"><CODE>listen()</CODE></A> queue. It defaults to SOMAXCONN if omitted. SocketFactory will ensure that ListenQueue doesn't exceed SOMAXCONN.</P> <P>It should go without saying that ListenQueue is only appropriate for listening sockets.</P> <P></P> <LI> RemoteAddress <P>RemoteAddress is the remote address to which the socket should connect. If present, the SocketFactory will create a connecting socket; otherwise, the SocketFactory will make a listening socket.</P> <P>The remote address may be a string containing a dotted quad, a host name, a packed Internet address, or a Unix socket path. It will be packed, with or without an accompanying RemotePort as necessary for the socket domain.</P> <P></P> <LI> RemotePort <P>RemotePort is the port to which the socket should connect. It is required for connecting Internet sockets and ignored in all other cases.</P> <P>The remote port may be a number, or a name in the /etc/services (or equivalent) database.</P> <P></P></UL> <LI> POE::Wheel::SocketFactory::event(...) <P>Please see POE::Wheel.</P> <P></P> <LI> POE::Wheel::SocketFactory::getsockname() <P>Returns the value of <A HREF="../../../../lib/Pod/perlfunc.html#item_getsockname"><CODE>getsockname()</CODE></A> as called with the SocketFactory's socket.</P> <P>This is useful for finding out what the SocketFactory's internal socket has bound to when it's been instructed to use BindAddress => INADDR_ANY and/or BindPort => INADDR_ANY.</P> <P></P></UL> <P> <HR> <H1><A NAME="events and parameters">EVENTS AND PARAMETERS</A></H1> <UL> <LI> SuccessState <P>The SuccessState parameter defines a state name or coderef to call upon a successful connect or accept. The operation it succeeds on depends on the type of socket created.</P> <P>For connecting sockets, the success state/coderef is called when the socket has connected. For listening sockets, the success state/coderef is called for each successfully accepted client connection.</P> <P>ARG0 contains the connected or accepted socket.</P> <P>For INET sockets, ARG1 and ARG2 hold the socket's remote address and port, respectively.</P> <P>For Unix client sockets, ARG1 contains the server address and ARG2 is undefined.</P> <P>According to _Perl Cookbook_, the remote address for accepted Unix domain sockets is undefined. So ARG0 and ARG1 are, too.</P> <P></P> <LI> FailureState <P>The FailureState parameter defines a state name or coderef to call when a socket error occurs. The SocketFactory knows what to do with EAGAIN, so that's not considered an error.</P> <P>The ARG0 parameter contains the name of the function that failed. ARG1 and ARG2 contain the numeric and string versions of $! at the time of the error, respectively.</P> <P>A sample ErrorState state:</P> <PRE> sub error_state { my ($operation, $errnum, $errstr) = @_[ARG0, ARG1, ARG2]; warn "$operation error $errnum: $errstr\n"; }</PRE> <P></P></UL> <P> <HR> <H1><A NAME="see also">SEE ALSO</A></H1> <P>POE::Wheel; POE::Wheel::FollowTail; POE::Wheel::ListenAccept; POE::Wheel::ReadWrite; POE::Wheel::SocketFactory</P> <P> <HR> <H1><A NAME="bugs">BUGS</A></H1> <P>Many (if not all) of the croak/carp/warn/die statements should fire back $state_failure instead.</P> <P> <HR> <H1><A NAME="authors & copyrights">AUTHORS & COPYRIGHTS</A></H1> <P>Please see the POE manpage.</P> <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%> <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc"> <STRONG><P CLASS=block> POE::Wheel::SocketFactory - POE Socket Creation Logic Abstraction</P></STRONG> </TD></TR> </TABLE> </BODY> </HTML>