1Net::Server::Proto(3) User Contributed Perl DocumentationNet::Server::Proto(3)
2
6 Net::Server::Proto - Net::Server Protocol compatibility layer
7
9 # Net::Server::Proto and its accompianying modules are not
10 # intended to be used outside the scope of Net::Server.
11 # That being said, here is how you use them. This is
13 # only intended for anybody wishing to extend the
14 # protocols to include some other set (ie maybe a
15 # database connection protocol)
16 use Net::Server::Proto;
18 my $sock = Net::Server::Proto->object(
20 $default_host, # host to use if none found in port
21 $port, # port to connect to
22 $default_proto, # proto to use if none found in port
23 $server_obj, # Net::Server object
24 );
25 ### Net::Server::Proto will attempt to interface with
28 ### sub modules named simillar to Net::Server::Proto::TCP
29 ### Individual sub modules will be loaded by
30 ### Net::Server::Proto as they are needed.
31 use Net::Server::Proto::TCP; # can be TCP/UDP/UNIX/etc
33 ### Return an object which is a sub class of IO::Socket
35 ### At this point the object is not connected.
36 ### The method can gather any other information that it
37 ### needs from the server object.
38 my $sock = Net::Server::Proto::TCP->object(
39 $default_host, # host to use if none found in port
40 $port, # port to connect to
41 $server_obj, # Net::Server object
42 );
43 ### Log that a connection is about to occur.
45 ### Use the facilities of the passed Net::Server object.
46 $sock->log_connect( $server );
47 ### Actually bind to port or socket file. This
49 ### is typically done by calling the configure method.
50 $sock->connect();
51 ### Allow for rebinding to an already open fileno.
53 ### Typically will just do an fdopen.
54 $sock->reconnect();
55 ### Return a unique identifying string for this sock that
57 ### can be used when reconnecting.
58 my $str = $sock->hup_string();
59 ### Return the proto that is being used by this module.
61 my $proto = $sock->NS_proto();
62
64 Net::Server::Proto is an intermediate module which returns IO::Socket
65 style objects blessed into its own set of classes (ie
66 Net::Server::Proto::TCP, Net::Server::Proto::UNIX).
67 Only three or four protocols come bundled with Net::Server. TCP, UDP,
69 UNIX, and eventually SSL. TCP is an implementation of SOCK_STREAM
70 across an INET socket. UDP is an implementation of SOCK_DGRAM across
71 an INET socket. UNIX uses a unix style socket file and lets the user
72 choose between SOCK_STREAM and SOCK_DGRAM (the default is SOCK_STREAM).
73 SSL is actually just a layer on top of TCP.
74 The protocol that is passed to Net::Server can be the name of another
76 module which contains the protocol bindings. If a protocol of
77 MyServer::MyTCP was passed, the socket would be blessed into that
78 class. If Net::Server::Proto::TCP was passed, it would get that class.
79 If a bareword, such as tcp, udp, unix or ssl, is passed, the word is
80 uppercased, and post pended to "Net::Server::Proto::" (ie tcp =
81 Net::Server::Proto::TCP).
82
84 Protocol names used by the Net::Server::Proto should be sub classes of
85 IO::Socket. These classes should also contain, as a minimum, the
86 following methods:
87 object
89 Return an object which is a sub class of IO::Socket At this point
90 the object is not connected. The method can gather any other
91 information that it needs from the server object. Arguments are
92 default_host, port, and a Net::Server style server object.
93 log_connect
95 Log that a connection is about to occur. Use the facilities of the
96 passed Net::Server object. This should be an informative string
97 explaining which properties are being used.
98 connect
100 Actually bind to port or socket file. This is typically done
101 internally by calling the configure method of the IO::Socket super
102 class.
103 reconnect
105 Allow for rebinding to an already open fileno. Typically will just
106 do an fdopen using the IO::Socket super class.
107 hup_string
109 Return a unique identifying string for this sock that can be used
110 when reconnecting. This is done to allow information including the
111 file descriptor of the open sockets to be passed via %ENV during an
112 exec. This string should always be the same based upon the
113 configuration parameters.
114 NS_proto
116 Net::Server protocol. Return the protocol that is being used by
117 this module. This does not have to be a registered or known
118 protocol.
119 show
121 Similar to log_connect, but simply shows a listing of which
122 properties were found. Can be used at any time.
123
125 The port is the most important argument passed to the sub module
126 classes and to Net::Server::Proto itself. For tcp, udp, and ssl style
127 ports, the form is generally host:port/protocol, host|port|protocol,
128 host/port, or port. For unix the form is generally
129 socket_file|type|unix or socket_file.
130 You can see what Net::Server::Proto parsed out by looking at the logs
132 to see what log_connect said. You could also include a post_bind_hook
133 similar to the following to debug what happened:
134 sub post_bind_hook {
136 my $self = shift;
137 foreach my $sock ( @{ $self->{server}->{sock} } ){
138 $self->log(2,$sock->show);
139 }
140 }
141 Rather than try to explain further, please look at the following
143 examples:
144 # example 1 ###################################
146 $port = "20203";
148 $def_host = "default_domain.com";
149 $def_proto = "tcp";
150 $obj = Net::Server::Proto->object($def_host,$port,$def_proto);
151 # ref = Net::Server::Proto::TCP
153 # NS_host = default_domain.com
154 # NS_port = 20203
155 # NS_proto = TCP
156 # example 2 ###################################
158 $port = "someother.com:20203";
160 $def_host = "default_domain.com";
161 $def_proto = "tcp";
162 $obj = Net::Server::Proto->object($def_host,$port,$def_proto);
163 # ref = Net::Server::Proto::TCP
165 # NS_host = someother.com
166 # NS_port = 20203
167 # NS_proto = TCP
168 # example 3 ###################################
170 $port = "someother.com:20203/udp";
172 $def_host = "default_domain.com";
173 $def_proto = "tcp";
174 $obj = Net::Server::Proto->object($def_host,$port,$def_proto);
175 # ref = Net::Server::Proto::UDP
177 # NS_host = someother.com
178 # NS_port = 20203
179 # NS_proto = UDP
180 # example 4 ###################################
182 $port = "someother.com:20203/Net::Server::Proto::UDP";
184 $def_host = "default_domain.com";
185 $def_proto = "TCP";
186 $obj = Net::Server::Proto->object($def_host,$port,$def_proto);
187 # ref = Net::Server::Proto::UDP
189 # NS_host = someother.com
190 # NS_port = 20203
191 # NS_proto = UDP
192 # example 5 ###################################
194 $port = "someother.com:20203/MyObject::TCP";
196 $def_host = "default_domain.com";
197 $def_proto = "tcp";
198 $obj = Net::Server::Proto->object($def_host,$port,$def_proto);
199 # ref = MyObject::TCP
201 # NS_host = someother.com
202 # NS_port = 20203
203 # NS_proto = TCP (depends on MyObject::TCP module)
204 # example 6 ###################################
206 $port = "/tmp/mysock.file|unix";
208 $def_host = "default_domain.com";
209 $def_proto = "tcp";
210 $obj = Net::Server::Proto->object($def_host,$port,$def_proto);
211 # ref = Net::Server::Proto::UNIX
213 # NS_host = undef
214 # NS_port = undef
215 # NS_unix_path = /tmp/mysock.file
216 # NS_unix_type = SOCK_STREAM
217 # NS_proto = UNIX
218 # example 7 ###################################
220 $port = "/tmp/mysock.file|".SOCK_DGRAM."|unix";
222 $def_host = "";
223 $def_proto = "tcp";
224 $obj = Net::Server::Proto->object($def_host,$port,$def_proto);
225 # ref = Net::Server::Proto::UNIX
227 # NS_host = undef
228 # NS_port = undef
229 # NS_unix_path = /tmp/mysock.file
230 # NS_unix_type = SOCK_DGRAM
231 # NS_proto = UNIX
232 # example 8 ###################################
234 $port = "/tmp/mysock.file|".SOCK_DGRAM."|unix";
236 $def_host = "";
237 $def_proto = "UNIX";
238 $obj = Net::Server::Proto->object($def_host,$port,$def_proto);
239 # ref = Net::Server::Proto::UNIX
241 # NS_host = undef
242 # NS_port = undef
243 # NS_unix_path = /tmp/mysock.file
244 # NS_unix_type = SOCK_DGRAM
245 # NS_proto = UNIX
246
248 Distributed under the same terms as Net::Server
249perl v5.12.0 2007-02-03 Net::Server::Proto(3)