Net::SCTP - A Stream Control Transmission Protocol(SCTP) module for Perl
use Net::SCTP;
lksctp-tools lksctp-tools-devel
An SCTP (Stream Control Transport Protocol) module created for Perl using XS with the Net extension because it is a net module.
SCTP is a streaming protocol of things like UDP and TCP. It is used in new technologies like LTE for phones. It streams data from multiple or one source to multiple or one source. If one connection is lost the data is not lost because it will continue to buffer until it gets the connection back and gets the rest of the message. It is also backwards compatible with TCP.
We used the draft 11 of the SCTP architecture for this module. A link is listed in the SEE ALSO section.
Tested on CentOS 5.2 with an i686 architecture using lksctp-tools-1.0.6-1.el5.1.i386 with IPv4.
This module has not been tested with IPv6, although the features are available.
Currently setsockopt is not fully working and has not been implemented. getsockopt is not implemented. sctp_peeloff has not been tested. Finally we have no support for sctp_opt_info. Eventually all of these will be supported, but for now you should be able to work without them.
Currently send(), recv(), sendto(), recvfrom(), read(), write(), and sctp_send() are not supported; however, may eventually be supported.
sctp_sendmsg & sctp_recvmsg do not currently support the use of parameters other than what you need to get them working.
Although there may be some code for the following functions they have not been tested. Furthermore they were not supported in our version of lksctp-tools so we had no way to implement them.
Functions: sctp_send, sctp_sendx, sctp_sendv, sctp_recvv
A server example can be seen in the directory with the program. One is also included here for good measure but the one in the directory is more extensive and has comments.
use Net::SCTP; my $port = 5556; my $message = 'I am the Server!!'; my $listen = 1; my $many = 1; my $single_host = "xxx.xxx.xx.xx"; my($client_message_length, $client_message, @hosts, $sctp_server, $ipv6, $auto_bind); # Create the server with one host or multiple hosts. if(!@hosts || @hosts <= 1) { $single_host = shift @hosts if @hosts == 1; @hosts = undef; $sctp_server = Net::SCTP->new( { LocalHost => $single_host, LocalPort => $port, Listen => $listen, OneToMany => $many, } ); } else { $sctp_server = Net::SCTP->new( { LocalHost => \@hosts, LocalPort => $port, Listen => $listen, OneToMany => $many, } ); } $sctp_server->socket(); $sctp_server->bind(); $sctp_server->listen(); while( $sctp_server->get_Socket() ) { $sctp_server->accept() if ! $many; ($client_message, $client_message_length) = $sctp_server->sctp_recvmsg(); print "\n" . $sctp_server->get_PeerHost(); print ":" . $sctp_server->get_PeerPort() . "\n"; print "Receiving Message: $client_message\n"; print "Size of: $client_message_length\n"; $sctp_server->sctp_sendmsg( $message ); } $sctp_server->close();
A client example can be seen in the directory with the program. One is also included here for good measure but the one in the directory is more extensive and has comments.
use Net::SCTP; my $single_host = "xxx.xxx.xx.xx"; my $dest_port = 5556; my $message = "I am the Client!!"; my $listen = 1; my $many = 1; my (@hosts, $message_length, $sctp_client); # Whether we have multiple hosts to connect to or one if(!@hosts || @hosts <= 1) { $single_host = shift @hosts if @hosts == 1; $sctp_client = Net::SCTP->new( { PeerHost => $single_host, PeerPort => $dest_port, Listen => $listen, OneToMany => $many, } ); } else { $sctp_client = Net::SCTP->new( { PeerHost => \@hosts, PeerPort => $dest_port, Listen => $listen, OneToMany => $many, } ); } $sctp_client->socket(); $sctp_client->connect(); $sctp_client->sctp_sendmsg( $message ); ($message, $message_length) = $sctp_client->sctp_recvmsg(); print "Received message: $message\n"; print "Size of: $message_length\n"; $sctp_client->close();
Creates a new Net::SCTP object. Net::SCTP provides the following key-value pairs:
LocalHost Local host bind address LocalPort Local host bind port PeerHost Remote host address PeerPort Remote port or service Listen Set to 1 to accept new connections OneToMany true for one-to-many and false one-to-one style connections Debug true will print debug info IPV6 true for an IPv6 network, defaults to false for IPv4
Sets up a socket descriptor.
Bind a server to a single IPv4 or IPv6 address. The $peer_host parameter is optional if the user provides a PeerHost in the new() function.
Connect to a single host. Connect can be called multiple times to create multiple connections on the same socket. If called before bind the server will automatically bind to what it needs if using listen.
The $peer_host parameter is optional if the user provides a PeerHost in the new() function.
By default, new associations are not accepted for one-to-many style sockets. An application uses listen() to mark a socket as being able to accept new associations. For one-to-one connection types you will need to use accept() instead.
Removes an established SCTP association from the accept queue of the endpoint. A new socket descriptor will be returned from accept() to represent the newly formed association.
Returns SCTP messages it receives and as a second parameter returns the message length. If the length of the message received is greater than $buffer_size, the message will be "chunked". This means that the received message will be broken up into several smaller messages with the length of each message being at most the $buffer_size.
Send a message on an open connection.
Pass an array reference to bind to multiple IPv4 or IPv6 addresses. If you provide this array reference to the LocalHost in the new() function, this parameter is optional.
Optionally pass an array reference to bind to connect to multiple IPv4 or IPv6 peer addresses. If you provide this array reference to the PeerHost in the new() function, this parameter is optional.
Close the connection on a socket.
Branch an association into a seperate socket.
Shutdown the connection on the socket.
Get the peer address you are connected to.
Get the local address you are connected to.
Set the options for a socket. This function takes a hash of hashes. The keys for the inner hash are the enumeration text for each socket option and the keys within those inner hashes are the variables for the respective struct. This function allows users to set multiple socket options in a single function call. It not necessary to provide the variables that you do not want to set.
**Note: Not all of the socket options have been implemented at this point. ***Note: No longer supported. It was breaking things.
Example:
$sctp_object->setsockopt( { SCTP_EVENTS => { sctp_data_io_event => 1, sctp_association_event => 1, sctp_authentication_event => 0 } }, SCTP_RTOINFO => { srto_initial => 5, }, );
Returns a hash of socket options similar to format described above in setsockopt. **Note: Not yet implemented
Performs server style start up for SCTP. This function is simply provided for convenience, you do not need to call this function to create an SCTP server.
Performs client style start up for SCTP. This function is simply provided for convenience, you do not need to call this function to create an SCTP client.
Query a socket descriptor for a peer address. This function is invoked by the server and will return the address and the length of the address for use.
This function will only work with one to one style sockets and is mostly for compatibility with older socket types like TCP. Use sctp_getpadders() for one to many type sockets.
Query a socket descriptor for a server address. This function is invoked by the peer and will return the address and the length of the address for use.
This function will only work with one to one style sockets and is mostly for compatibility with older socket types like TCP. Use sctp_getladders() for one to many type sockets.
The documentation for SCTP, that this module was built off of: http://tools.ietf.org/html/draft-ietf-tsvwg-sctpsocket-11
Anthony Lucillo <alucillo@cpan.org>
Brandon Casey <bcasey@cpan.org>
Copyright (C) 2013 by Brandon Casey & Anthony Lucillo
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.
To install Net::SCTP, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::SCTP
CPAN shell
perl -MCPAN -e shell install Net::SCTP
For more information on module installation, please visit the detailed CPAN module installation guide.