13
13
<!-- = incidental or special damages arising in any way out of the use = -->
14
14
<!-- = of this software. = -->
15
15
<!-- ====================================================================== -->
16
<!-- = copyright (c) 1999-2007 - amaury darsch = -->
16
<!-- = copyright (c) 1999-2011 - amaury darsch = -->
17
17
<!-- ====================================================================== -->
19
19
<appendix module="net" number="ii">
20
<title>Mail services reference</title>
22
<!-- =================================================================== -->
23
<!-- = mail object = -->
24
<!-- =================================================================== -->
26
<object nameset="afnix:net">
31
The <code>Mail</code> class is a mail delivery object which
32
manages to contact a <em>Mail Transport Agent</em> or MTA in order
33
to deliver a message to one or several recipients. By default, the
34
object contacts the local MTA, but this behavior can be changed
35
with the <code>set-mta-address</code> method. The class implements
36
the recipient an address syntax scheme as specified by RFC822. At
37
construction, the instance is empty. Only the recipient address
38
needs to be specified. The <code>send</code> method send the
39
message by contacting the MTA. If an error occurs, an exception is
57
The <code>Mail</code> constructor create a a default message
58
which is empty. The recipient addresses and the subject must be
59
specified for a successful message delivery.
71
The <code>to</code> method adds one or several address to the
72
<em>destination list</em>. The address format must conform to
73
RFC822. Multiple address are coma separated. Multiple call to this
83
The <code>cc</code> method adds one or several address to the
84
<em>copy list</em>. The address format must conform to
85
RFC822. Multiple address are coma separated. Multiple call to
86
this method is possible.
95
The <code>bcc</code> method adds one or several address to the
96
<em>blind copy list</em>. The address format must conform to
97
RFC822. Multiple address are coma separated. Multiple call to this
98
method is possible. The <em>blind copy list</em> is not included in
106
<args>String ...</args>
108
The <code>add</code> method adds one or several literals to the
109
message buffer. This is the normal way to fill a message buffer
117
<args>String ...</args>
119
The <code>addln</code> method adds one or several literals to
120
the message buffer. A newline character is added at the end of
121
the line. This is a similar way to fill a message buffer by
131
The <code>send</code> method request a message delivery by
132
contacting the MTA. Once the MTA has been contacted, the message
133
header and the message body is transferred. The MTA is
134
responsible to deliver the message to the appropriate
144
The <code>subject</code> method sets the message subject string
150
<name>set-mta-address</name>
154
The <code>set-mta-address</code> method sets the MTA IP address
155
that the class needs to contact for mail request. The address
156
can be an fully qualified host name or an IP number.
161
<name>get-mta-address</name>
165
The <code>get-mta-address</code> method returns the current MTA
166
IP address for this mail object.
171
<name>set-mta-port</name>
175
The <code>set-mta-port</code> method set the current MTA IP port
176
number for this mail object. With the MTA IP address, the MTA to
177
contact for mail request is uniquely defined. The default port
183
<name>get-mta-port</name>
187
The <code>get-mta-port</code> method returns the current MTA IP
188
port number for this mail object. The default port value is 25.
20
<title>Network sockets reference</title>
22
<!-- =================================================================== -->
23
<!-- = socket object = -->
24
<!-- =================================================================== -->
26
<object nameset="afnix:net">
31
The <code>Socket</code> class is a base class for the <afnix/>
32
network services. The class is automatically constructed by a
33
derived class and provide some common methods for all socket
42
<name>InputStream</name>
43
<name>OutputStream</name>
49
<name>REUSE-ADDRESS</name>
51
The <code>REUSE-ADDRESS</code> constant is used by the
52
<code>set-option</code> method to enable socket address
53
reuse. This option changes the rules that validates the address
54
used by bind. It is not recommended to use that option as it
55
decreases TCP reliability.
60
<name>BROADCAST</name>
62
The <code>BROADCAST</code> constant is used by the
63
<code>set-option</code> method to enable broadcast of
64
packets. This options only works with IP version 4 address. The
65
argument is a boolean flag only.
70
<name>DONT-ROUTE</name>
72
The <code>DONT-ROUTE</code> constant is used by the
73
<code>set-option</code> method to control if a packet is to be
74
sent via the routing table. This option is rarely used with
75
<afnix/>. The argument is a boolean flag only.
80
<name>KEEP-ALIVE</name>
82
The <code>KEEP-ALIVE</code> constant is used by the
83
<code>set-option</code> method to check periodically if the
84
connection is still alive. This option is rarely used with
85
<afnix/>. The argument is a boolean flag only.
92
The <code>LINGER</code> constant is used by the
93
<code>set-option</code> method to turn on or off the lingering
94
on close. If the first argument is true, the second argument is
100
<name>RCV-SIZE</name>
102
The <code>RCV-SIZE</code> constant is used by the
103
<code>set-option</code> method to set the receive buffer size.
108
<name>SND-SIZE</name>
110
The <code>SND-SIZE</code> constant is used by the
111
<code>set-option</code> method to set the send buffer size.
116
<name>HOP-LIMIT</name>
118
The <code>HOP-LIMIT</code> constant is used by the
119
<code>set-option</code> method to set packet hop limit.
124
<name>MULTICAST-LOOPBACK</name>
126
The <code>MULTICAST-LOOPBACK</code> constant is used by the
127
<code>set-option</code> method to control whether or not
128
multicast packets are copied to the loopback. The argument is a
134
<name>MULTICAST-HOP-LIMIT</name>
136
The <code>MULTICAST-HOP-LIMIT</code> constant is used by the
137
<code>set-option</code> method to set the hop limit for
143
<name>MAX-SEGMENT-SIZE</name>
145
The <code>MAX-SEGMENT-SIZE</code> constant is used by the
146
<code>set-option</code> method to set the TCP maximum segment size.
151
<name>NO-DELAY</name>
153
The <code>NO-DELAY</code> constant is used by the
154
<code>set-option</code> method to enable or disable the Naggle
167
The <code>bind</code> method binds this socket to the port
168
specified as the argument.
175
<args>Integer Address</args>
177
The <code>bind</code> method binds this socket to the port
178
specified as the first argument and the address specified as the
186
<args>Integer Address [Boolean]</args>
188
The <code>connect</code> method connects this socket to the port
189
specified as the first argument and the address specified as the
190
second argument. A connected socket is useful with udp client
191
that talks only with one fixed server. The optional third
192
argument is a boolean flag that permits to select whether or not
193
the alias addressing scheme should be used. If the flag is false,
194
the default address is used. If the flag is true, an attempt is
195
made to connect to the first successful address that is part
205
The <code>open-p</code> predicate returns true if the socket is
206
open. The method checks that a descriptor is attached to the
207
object. This does not mean that the descriptor is valid in the
208
sense that one can read or write on it. This method is useful to
209
check if a socket has not been closed.
214
<name>shutdown</name>
216
<args>none|Boolean</args>
218
The <code>shutdown</code> method shutdowns or close the
219
connection. Without argument, the connection is closed without
220
consideration for those symbols attached to the object. With one
221
argument, the connection is closed in one direction only. If the
222
mode argument is false, further receive is disallowed. If the
223
mode argument is true, further send is disallowed. The method
224
returns true on success, false otherwise.
233
The <code>ipv6-p</code> predicate returns true if the socket
234
address is an IP version 6 address, false otherwise.
239
<name>get-socket-address</name>
243
The <code>get-socket-address</code> method returns an address
244
object of the socket. The returned object can be later used to
245
query the canonical name and the ip address.
250
<name>get-socket-port</name>
254
The <code>get-socket-port</code> method returns the port
255
number of the socket.
260
<name>get-socket-authority</name>
264
The <code>get-socket-authority</code> method returns the authority
265
string in the form of an address and port pair of the socket.
270
<name>get-peer-address</name>
274
The <code>get-peer-address</code> method returns an address
275
object of the socket's peer. The returned object can be later
276
used to query the canonical name and the ip address.
281
<name>get-peer-port</name>
285
The <code>get-peer-port</code> method returns the port
286
number of the socket's peer.
291
<name>get-peer-authority</name>
295
The <code>get-peer-authority</code> method returns the authority
296
string in the form of an address and port pair of the socket's peer.
301
<name>set-option</name>
303
<args>constant [Boolean|Integer] [Integer]</args>
305
The <code>set-option</code> method set a socket option. The
306
first argument is the option to set. The second argument is a
307
boolean value which turn on or off the option. The optional
308
third argument is an integer needed for some options.
313
<name>set-encoding-mode</name>
315
<args>Item|String</args>
317
The <code>set-encoding-mode</code> method sets the input and
318
output encoding mode. In the first form, with an item, the
319
stream encoding mode is set directly. In the second form, the
320
encoding mode is set with a string and might also alter the
321
stream transcoing mode.
326
<name>set-input-encoding-mode</name>
328
<args>Item|String</args>
330
The <code>set-input-encoding-mode</code> method sets the input
331
encoding mode. In the first form, with an item, the
332
stream encoding mode is set directly. In the second form, the
333
encoding mode is set with a string and might also alter the
334
stream transcoing mode.
339
<name>get-input-encoding-mode</name>
343
The <code>get-input-encoding-mode</code> method return the input
349
<name>set-output-encoding-mode</name>
351
<args>Item|String</args>
353
The <code>set-output-encoding-mode</code> method sets the output
354
encoding mode. In the first form, with an item, the
355
stream encoding mode is set directly. In the second form, the
356
encoding mode is set with a string and might also alter the
357
stream transcoing mode.
362
<name>get-output-encoding-mode</name>
366
The <code>get-output-encoding-mode</code> method return the output
373
<!-- =================================================================== -->
374
<!-- = tcp socket object = -->
375
<!-- =================================================================== -->
377
<object nameset="afnix:net">
378
<name>TcpSocket</name>
382
The <code>TcpSocket</code> class is a base class for all tcp
383
socket objects. The class is derived from the <code>Socket</code>
384
class and provides some specific tcp methods. If a
385
<code>TcpSocket</code> is created, the user is responsible to
386
connect it to the proper address and port.
390
<pred>tcp-socket-p</pred>
397
<!-- constructors -->
400
<name>TcpSocket</name>
403
The <code>TcpSocket</code> constructor creates a new tcp socket.
412
<retn>TcpSocket</retn>
415
The <code>accept</code> method waits for incoming connection and
416
returns a <code>TcpSocket</code> object initialized with the
417
connected peer. The result socket can be used to perform i/o
418
operations. This method is used by tcp server.
425
<args>none|Integer</args>
427
The <code>listen</code> method initialize a socket to accept
428
incoming connection. Without argument, the default number of
429
incoming connection is 5. The integer argument can be used to
430
specify the number of incoming connection that socket is willing
431
to queue. This method is used by tcp server.
437
<!-- =================================================================== -->
438
<!-- = tcp client object = -->
439
<!-- =================================================================== -->
441
<object nameset="afnix:net">
442
<name>TcpClient</name>
446
The <code>TcpClient</code> class creates a tcp client by host and
447
port. The host argument can be either a name or an address
448
object. The port argument is the server port to contact. The
449
<code>TcpClient</code> class is derived from the
450
<code>TcpSocket</code> class. This class has no specific methods.
454
<pred>tcp-client-p</pred>
458
<name>TcpSocket</name>
461
<!-- constructors -->
464
<name>TcpClient</name>
465
<args>String Integer</args>
467
The <code>TcpClient</code> constructor creates a new tcp client
468
socket by host name and port number.
474
<!-- =================================================================== -->
475
<!-- = tcp server object = -->
476
<!-- =================================================================== -->
478
<object nameset="afnix:net">
479
<name>TcpServer</name>
483
The <code>TcpServer</code> class creates a tcp server by port. An
484
optional host argument can be either a name or an address
485
object. The port argument is the server port to bind. The
486
<code>TcpServer</code> class is derived from the
487
<code>TcpSocket</code> class. This class has no specific
488
methods. With one argument, the server bind the port argument on
489
the local host. The backlog can be specified as the last
490
argument. The host name can also be specified as the first
491
argument, the port as second argument and eventually the
492
backlog. Note that the host can be either a string or an address
497
<pred>tcp-server-p</pred>
501
<name>TcpSocket</name>
504
<!-- constructors -->
507
<name>TcpServer</name>
510
The <code>TcpServer</code> constructor creates a default tcp
516
<name>TcpServer</name>
519
The <code>TcpServer</code> constructor creates a default tcp
520
server which is bound on the specified port argument.
525
<name>TcpServer</name>
526
<args>Integer Integer</args>
528
The <code>TcpServer</code> constructor creates a default tcp
529
server which is bound on the specified port argument. The second
530
argument is the backlog value.
535
<name>TcpServer</name>
536
<args>String Integer</args>
538
The <code>TcpServer</code> constructor creates a tcp server by
539
host name and port number. The first argument is the host
540
name. The second argument is the port number.
545
<name>TcpServer</name>
546
<args>String Integer Integer</args>
548
The <code>TcpServer</code> constructor creates a tcp server by
549
host name and port number. The first argument is the host
550
name. The second argument is the port number. The third argument
557
<!-- =================================================================== -->
558
<!-- = datagram object = -->
559
<!-- =================================================================== -->
561
<object nameset="afnix:net">
562
<name>Datagram</name>
566
The <code>Datagram</code> class is a socket class used by udp
567
socket. A datagram is constructed by the <code>UdpSocket</code>
568
<code>accept</code> method. The purpose of a datagram is to store
569
the peer information so one can reply to the sender. The datagram
570
also stores in a buffer the data sent by the peer. This class does
571
not have any constructor nor any specific method.
575
<pred>datagram-p</pred>
583
<!-- =================================================================== -->
584
<!-- = udp socket object = -->
585
<!-- =================================================================== -->
587
<object nameset="afnix:net">
588
<name>UdpSocket</name>
592
The <code>UdpSocket</code> class is a base class for all udp
593
socket objects. The class is derived from the <code>Socket</code>
594
class and provides some specific udp methods.
598
<pred>udp-socket-p</pred>
605
<!-- constructors -->
608
<name>UdpSocket</name>
611
The <code>UdpSocket</code> constructor creates a new udp socket.
620
<retn>Datagram</retn>
623
The <code>accept</code> method waits for an incoming datagram
624
and returns a <code>Datagram</code> object. The datagram is
625
initialized with the peer address and port as well as the
632
<!-- =================================================================== -->
633
<!-- = udp client object = -->
634
<!-- =================================================================== -->
636
<object nameset="afnix:net">
637
<name>UdpClient</name>
641
The <code>UdpClient</code> class creates a udp client by host and
642
port. The host argument can be either a name or an address
643
object. The port argument is the server port to contact. The
644
<code>UdpClient</code> class is derived from the
645
<code>UdpSocket</code> class. This class has no specific methods.
649
<pred>udp-client-p</pred>
653
<name>UdpSocket</name>
656
<!-- constructors -->
659
<name>UdpClient</name>
660
<args>String Integer</args>
662
The <code>UdpClient</code> constructor creates a new udp client
663
by host and port. The first argument is the host name. The
664
second argument is the port number.
670
<!-- =================================================================== -->
671
<!-- = udp server object = -->
672
<!-- =================================================================== -->
674
<object nameset="afnix:net">
675
<name>UdpServer</name>
679
The <code>UdpServer</code> class creates a udp server by port. An
680
optional host argument can be either a name or an address
681
object. The port argument is the server port to bind. The
682
<code>UdpServer</code> class is derived from the
683
<code>UdpSocket</code> class. This class has no specific
684
methods. With one argument, the server bind the port argument on
685
the local host. The host name can also be specified as the first
686
argument, the port as second argument. Note that the host can be
687
either a string or an address object.
691
<pred>udp-server-p</pred>
695
<name>UdpSocket</name>
698
<!-- constructors -->
701
<name>UdpServer</name>
704
The <code>UdpServer</code> constructor creates a default udp
710
<name>UdpServer</name>
711
<args>String|Address</args>
713
The <code>UdpServer</code> constructor creates a udp server
714
object by host. The first argument is the host name or host address.
719
<name>UdpServer</name>
720
<args>String|Address Integer</args>
722
The <code>UdpServer</code> constructor creates a udp server
723
object by host and port. The first argument is the host name or
724
host address. The second argument is the port number.
730
<!-- =================================================================== -->
731
<!-- = multicast object = -->
732
<!-- =================================================================== -->
734
<object nameset="afnix:net">
735
<name>Multicast</name>
739
The <code>Multicast</code> class creates a udp multicast socket by
740
port. An optional host argument can be either a name or an address
741
object. The port argument is the server port to bind. The
742
<code>Multicast</code> class is derived from the
743
<code>UdpSocket</code> class. This class has no specific
744
methods. With one argument, the server bind the port argument on
745
the local host. The host name can also be specified as the first
746
argument, the port as second argument. Note that the host can be
747
either a string or an address object. This class is similar to the
748
<code>UdpServer</code> class, except that the socket join the
749
multicast group at construction and leave it at destruction.
753
<pred>multicast-p</pred>
757
<name>UdpSocket</name>
760
<!-- constructors -->
763
<name>Multicast</name>
764
<args>String|Address</args>
766
The <code>Multicast</code> constructor creates a multicast socket
767
object by host. The first argument is the host name or host address.
772
<name>Multicast</name>
773
<args>String|Address Integer</args>
775
The <code>Multicast</code> constructor creates a multicast socket
776
object by host and port. The first argument is the host name or
777
host address. The second argument is the port number.
added
removed
src/mod/net/doc/appendix-ii.xml
