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
27 ### sub modules named simillar to Net::Server::Proto::TCP
28 ### Individual sub modules will be loaded by
29 ### Net::Server::Proto as they are needed.
30 use Net::Server::Proto::TCP; # can be TCP/UDP/UNIX/etc
32 ### Return an object which is a sub class of IO::Socket
34 ### At this point the object is not connected.
35 ### The method can gather any other information that it
36 ### needs from the server object.
37 my $sock = Net::Server::Proto::TCP->object(
38 $default_host, # host to use if none found in port
39 $port, # port to connect to
40 $server_obj, # Net::Server object
41 );
42 ### Log that a connection is about to occur.
44 ### Use the facilities of the passed Net::Server object.
45 $sock->log_connect( $server );
46 ### Actually bind to port or socket file. This
48 ### is typically done by calling the configure method.
49 $sock->connect();
50 ### Allow for rebinding to an already open fileno.
52 ### Typically will just do an fdopen.
53 $sock->reconnect();
54 ### Return a unique identifying string for this sock that
56 ### can be used when reconnecting.
57 my $str = $sock->hup_string();
58 ### Return the proto that is being used by this module.
60 my $proto = $sock->NS_proto();
61
63 Net::Server::Proto is an intermediate module which returns IO::Socket
64 style objects blessed into its own set of classes (ie
65 Net::Server::Proto::TCP, Net::Server::Proto::UNIX).
66 Only three or four protocols come bundled with Net::Server. TCP, UDP,
68 UNIX, and eventually SSL. TCP is an implementation of SOCK_STREAM
69 across an INET socket. UDP is an implementation of SOCK_DGRAM across
70 an INET socket. UNIX uses a unix style socket file and lets the user
71 choose between SOCK_STREAM and SOCK_DGRAM (the default is SOCK_STREAM).
72 SSL is actually just a layer on top of TCP.
73 The protocol that is passed to Net::Server can be the name of another
75 module which contains the protocol bindings. If a protocol of
76 MyServer::MyTCP was passed, the socket would be blessed into that
77 class. If Net::Server::Proto::TCP was passed, it would get that class.
78 If a bareword, such as tcp, udp, unix or ssl, is passed, the word is
79 uppercased, and post pended to "Net::Server::Proto::" (ie tcp =
80 Net::Server::Proto::TCP).
81
83 Protocol names used by the Net::Server::Proto should be sub classes of
84 IO::Socket. These classes should also contain, as a minimum, the fol‐
85 lowing methods:
86 object
88 Return an object which is a sub class of IO::Socket At this point
89 the object is not connected. The method can gather any other
90 information that it needs from the server object. Arguments are
91 default_host, port, and a Net::Server style server object.
92 log_connect
94 Log that a connection is about to occur. Use the facilities of the
95 passed Net::Server object. This should be an informative string
96 explaining which properties are being used.
97 connect
99 Actually bind to port or socket file. This is typically done
100 internally by calling the configure method of the IO::Socket super
101 class.
102 reconnect
104 Allow for rebinding to an already open fileno. Typically will just
105 do an fdopen using the IO::Socket super class.
106 hup_string
108 Return a unique identifying string for this sock that can be used
109 when reconnecting. This is done to allow information including the
110 file descriptor of the open sockets to be passed via %ENV during an
111 exec. This string should always be the same based upon the config‐
112 uration parameters.
113 NS_proto
115 Net::Server protocol. Return the protocol that is being used by
116 this module. This does not have to be a registered or known proto‐
117 col.
118 show
120 Similar to log_connect, but simply shows a listing of which proper‐
121 ties were found. Can be used at any time.
122
124 The port is the most important argument passed to the sub module
125 classes and to Net::Server::Proto itself. For tcp, udp, and ssl style
126 ports, the form is generally host:port/protocol, host⎪port⎪protocol,
127 host/port, or port. For unix the form is generally
128 socket_file⎪type⎪unix or socket_file.
129 You can see what Net::Server::Proto parsed out by looking at the logs
131 to see what log_connect said. You could also include a post_bind_hook
132 similar to the following to debug what happened:
133 sub post_bind_hook {
135 my $self = shift;
136 foreach my $sock ( @{ $self->{server}->{sock} } ){
137 $self->log(2,$sock->show);
138 }
139 }
140 Rather than try to explain further, please look at the following exam‐
142 ples:
143 # example 1 ###################################
145 $port = "20203";
147 $def_host = "default_domain.com";
148 $def_proto = "tcp";
149 $obj = Net::Server::Proto->object($def_host,$port,$def_proto);
150 # ref = Net::Server::Proto::TCP
152 # NS_host = default_domain.com
153 # NS_port = 20203
154 # NS_proto = TCP
155 # example 2 ###################################
157 $port = "someother.com:20203";
159 $def_host = "default_domain.com";
160 $def_proto = "tcp";
161 $obj = Net::Server::Proto->object($def_host,$port,$def_proto);
162 # ref = Net::Server::Proto::TCP
164 # NS_host = someother.com
165 # NS_port = 20203
166 # NS_proto = TCP
167 # example 3 ###################################
169 $port = "someother.com:20203/udp";
171 $def_host = "default_domain.com";
172 $def_proto = "tcp";
173 $obj = Net::Server::Proto->object($def_host,$port,$def_proto);
174 # ref = Net::Server::Proto::UDP
176 # NS_host = someother.com
177 # NS_port = 20203
178 # NS_proto = UDP
179 # example 4 ###################################
181 $port = "someother.com:20203/Net::Server::Proto::UDP";
183 $def_host = "default_domain.com";
184 $def_proto = "TCP";
185 $obj = Net::Server::Proto->object($def_host,$port,$def_proto);
186 # ref = Net::Server::Proto::UDP
188 # NS_host = someother.com
189 # NS_port = 20203
190 # NS_proto = UDP
191 # example 5 ###################################
193 $port = "someother.com:20203/MyObject::TCP";
195 $def_host = "default_domain.com";
196 $def_proto = "tcp";
197 $obj = Net::Server::Proto->object($def_host,$port,$def_proto);
198 # ref = MyObject::TCP
200 # NS_host = someother.com
201 # NS_port = 20203
202 # NS_proto = TCP (depends on MyObject::TCP module)
203 # example 6 ###################################
205 $port = "/tmp/mysock.file⎪unix";
207 $def_host = "default_domain.com";
208 $def_proto = "tcp";
209 $obj = Net::Server::Proto->object($def_host,$port,$def_proto);
210 # ref = Net::Server::Proto::UNIX
212 # NS_host = undef
213 # NS_port = undef
214 # NS_unix_path = /tmp/mysock.file
215 # NS_unix_type = SOCK_STREAM
216 # NS_proto = UNIX
217 # example 7 ###################################
219 $port = "/tmp/mysock.file⎪".SOCK_DGRAM."⎪unix";
221 $def_host = "";
222 $def_proto = "tcp";
223 $obj = Net::Server::Proto->object($def_host,$port,$def_proto);
224 # ref = Net::Server::Proto::UNIX
226 # NS_host = undef
227 # NS_port = undef
228 # NS_unix_path = /tmp/mysock.file
229 # NS_unix_type = SOCK_DGRAM
230 # NS_proto = UNIX
231 # example 8 ###################################
233 $port = "/tmp/mysock.file⎪".SOCK_DGRAM."⎪unix";
235 $def_host = "";
236 $def_proto = "UNIX";
237 $obj = Net::Server::Proto->object($def_host,$port,$def_proto);
238 # ref = Net::Server::Proto::UNIX
240 # NS_host = undef
241 # NS_port = undef
242 # NS_unix_path = /tmp/mysock.file
243 # NS_unix_type = SOCK_DGRAM
244 # NS_proto = UNIX
245
247 Distributed under the same terms as Net::Server
248perl v5.8.8 2007-02-03 Net::Server::Proto(3)