NAME

Net::SCTP - A Stream Control Transmission Protocol(SCTP) module for Perl

USE

  use Net::SCTP;

REQUIRED INSTALL

lksctp-tools lksctp-tools-devel

DESCRIPTION

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.

CURRENT STATE

    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.

UNSUPPORTED

    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

SAMPLE CODE

SERVER EXAMPLE

    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();

CLIENT EXAMPLE

    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();

CONSTRUCTOR

new ( \%ARGS )

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

METHODS

socket ()

Sets up a socket descriptor.

bind ( $peer_host )

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 ( $peer_host )

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.

listen ()

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.

accept ()

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.

($message, $message_length) = sctp_recvmsg ( $buffer_size, $flags )

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.

sctp_sendmsg ( $message )

Send a message on an open connection.

bindx ( \@local_addresses, $flag )

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.

sctp_connectx ( \@peer_host )

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 ()

Close the connection on a socket.

sctp_peeloff ()

Branch an association into a seperate socket.

shutdown ()

Shutdown the connection on the socket.

sctp_getpadders ()

Get the peer address you are connected to.

sctp_getladders ()

Get the local address you are connected to.

setsockopt ( \%hash )

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,
        },
      );
getsockopt ()

Returns a hash of socket options similar to format described above in setsockopt. **Note: Not yet implemented

start_server ()

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.

start_client ()

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.

($peer_ip , $peer_length) = getpeername ()

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.

The $peer_host parameter is optional if the user provides a PeerHost in the new() function.

($local_ip , $local_length) = getsockname ()

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.

SEE ALSO

The documentation for SCTP, that this module was built off of: http://tools.ietf.org/html/draft-ietf-tsvwg-sctpsocket-11

AUTHORS

Anthony Lucillo <alucillo@cpan.org>

Brandon Casey <bcasey@cpan.org>

COPYRIGHT LICENSE

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/>.