The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Net-SDP-0.07
River stage zero No dependents
++
/ Net::SDP

NAME

Net::SDP - Session Description Protocol (rfc2327)

SYNOPSIS

  use Net::SDP;

  my $sdp = Net::SDP->new();
  
  $sdp->parse_file( 'myfile.sdp' );
  
  print "Session name: ".$sdp->session_name()."\n";
  print "Session info: ".$sdp->session_info()."\n";
  print "Session tool: ".$sdp->session_attribute('tool')."\n";
  
  $sdp->session_info( "This is my session" );
  
  print $sdp->generate();

DESCRIPTION

Net::SDP is an SDP (Session Description Protocol) parser and generator. Net::SDP is object oriented and a single instance of Net::SDP represents a single SDP session description. There are methods to easily get, set and create each of the fields in the session description.

The classes Net::SDP::Time and Net::SDP::Media are automatically instantiated for each Time Description (t=) and Media Description (m=).

METHODS

new( [source] )

Creates a new Net::SDP session description object with default values for the required fields.

If the optional paramater source is specified, then it is passed to parse(). If parsing fails, than new() will return undef.

parse( source )

Parses in an SDP description. This method tries to work our the source of the SDP data automatically and is ideal for use with command line tools. The source may be a path to a file, a URL, a Net::SAP::Packet object, SDP data itself or if undefined will be read in on STDIN. Returns 1 if successful, or 0 on failure.

NOTE: it is faster to pass SDP data straight into the new() method, as it does not then initialise the object with default values, this involves doing DNS lookups to find out the name of the local host.

parse_file( filepath )

Parses in an SDP description from the specified file path. Returns 1 if successful, or 0 on failure.

parse_url( url )

Parses in an SDP description from the specified URL. LWP (libwww-perl) is required for this method. Returns 1 if successful, or 0 on failure.

parse_stdin()

Parses in an SDP description from STDIN. Returns 1 if successful, or 0 on failure.

parse_data( sdpdata )

Parses the SDP description data passed as parameter. Returns 1 if successful, or 0 on failure.

generate()

Generates and returns SDP description. Note that you must have set the compulsory fields and have at least one Time Description for the SDP description to be valid.

session_origin()

Get or Set the whole of the session origin field. [o=]

Example:

        $origin = $sdp->session_origin();
        $sdp->session_origin( 'njh 3303643609 3303643669 IN IP4 152.78.104.83' );
session_origin_username()

Get or Set the username subfield of the session origin field. [o=]

Example:

        $username = $sdp->session_origin_username();
        $sdp->session_origin_username( 'njh' );
session_origin_id()

Get or Set the ID subfield of the session origin field. This should be an NTP timestamp. [o=]

Example:

        $id = $sdp->session_origin_id();
        $sdp->session_origin_id( 3303643609 );
session_origin_version()

Get or Set the version subfield of the session origin field. This should be an NTP timestamp. [o=]

Example:

        $version = $sdp->session_origin_version();
        $sdp->session_origin_version( 3303643669 );
session_origin_net_type()

Get or Set the network type subfield of the session origin field. In most cases this will be 'IN'. [o=]

Example:

        $net_type = $sdp->session_origin_net_type();
        $sdp->session_origin_net_type( 'IN' );
session_origin_addr_type()

Get or Set the address type subfield of the session origin field. In most cases this will be 'IP4'. [o=]

Example:

        $addr_type = $sdp->session_origin_addr_type();
        $sdp->session_origin_addr_type( 'IP6' );
session_origin_address()

Get or Set the address subfield of the session origin field. This may be a fully qualified domain name or global IP address but must not be a private IP or localhost. [o=]

Example:

        $address = $sdp->session_origin_address();
        $sdp->session_origin_address( '152.78.104.83' );
session_identifier()

Returns a unqiue identifier string of this sessions origin. It contains all of the sub fields in the origin field apart from the version subfield. [o=]

Example:

        $ident = $sdp->session_identifier();
session_name()

Get or Set the session name field. [s=]

Example:

        $name = $sdp->session_name();
        $sdp->session_name( 'My Cool Session' );
session_info()

Get or Set the session information/description field. [i=]

Example:

        $name = $sdp->session_info();
        $sdp->session_info( 'Broadcast live from Southampton' );
session_uri()

Get or Set the session URI field. Used by WWW clients to get more information about the session. [u=]

Example:

        $name = $sdp->session_uri();
        $sdp->session_uri( 'http://www.surgeradio.co.uk' );
session_email()

Get or Set the session email field. Although uncommon, more than one email address field is valid. You can set multiple email addresses by passing them in an ARRAYREF. This method will only return the first email address. [e=]

Example:

        $email = $sdp->session_email();
        $sdp->session_email( 'njh@ecs.soton.ac.uk' );
        $sdp->session_email( ['njh@ecs.soton.ac.uk', 'njh@surgeradio.co.uk'] );
session_email_arrayref()

Returns all email addresses as an array reference. Will return an empty ARRAYREF if no email addresses are available.

session_phone()

Get or Set the session telephone number field. Although uncommon, more than one phone number field is valid. You can set multiple phone numbers by passing them in an ARRAYREF. This method will only return the first phone number. [p=]

Example:

        $phone = $sdp->session_phone();
        $sdp->session_phone( '+44 870 357 2287' );
        $sdp->session_phone( ['0870 357 2287', '41287'] );
session_phone_arrayref()

Returns all phone numbers as an array reference. Will return an empty ARRAYREF if no phone numbers are available.

session_key( method, [key] )

Get or Set the session encryption key field. When setting the key parameter is optional - dependant on the method. [k=]

Example:

        ($method, $key) = $sdp->session_key();
        $sdp->session_key( 'prompt' );
        $sdp->session_key( 'base64', 'AoItAE8BAQ8DAQOBQwA' );
session_attribute( name, [value] )

Get or Set an attribute for this session description. [a=]

When setting an attribute, if you pass in a scalar, then all attributes with the same name will be replaced. Alternively an attribute may be set to multiple values by passing an ARRAYREF. If an attribute does not require it, then the value parameter is optional - eg for 'recvonly' attribute.

When getting an attribute that has no value, then '' is returned, or if the attribute does not exists then undef is returned. If the attribute has a single value, then that value is returned, or if it has more than one value then an ARRAYREF is returned.

Example:

        $tool = $sdp->session_attribute( 'tool' );
        $sdp->session_attribute( 'recvonly' );
session_attributes()

Get a HASHREF of all the attributes associated with this session description [a=]

Example:

        $hashref = $sdp->session_attributes();
session_add_attribute( name, [value] )

Add a value for sepecified attribute. This method is intended to be used with attributes with multiple values - eg lang [a=]

Example:

        $audio->session_add_attribute( 'lang', 'en');
        $audio->session_add_attribute( 'lang', 'fr');
session_del_attribute( name )

Deletes all attributes of given name. Example:

        $audio->session_del_attribute( 'lang' );
media_desc_of_type( type )

Returns the first media description (as a Net::SDP::Media) of the specified type.

Example:

        $audio = $sdp->media_desc_of_type( 'audio' );
media_desc_arrayref( )

Returns an ARRAYREF of all the media descriptions - Net::SDP::Media objects.

media_desc_delete_all()

Deletes all media descriptors.

media_desc_delete( $num )

Delete media description with index $num. Returns 0 if successful or 1 on failure.

time_desc( [$num] )

Returns the time description with index number $num. Returns the first time description if, $num is undefined. Return undef if no time description of chosen index is available. Returns a Net::SDP::Time.

time_desc_arrayref()

Returns an ARRAYREF of all the time descriptions - Net::SDP::Time objects.

time_desc_delete_all()

Deletes all time descriptors.

time_desc_delete( $num )

Delete time description with index $num. Returns 0 if successful or 1 on failure.

new_time_desc()

Creates a new time description for the session and returns a new Net::SDP::Time object.

new_media_desc( [type] )

Creates a new media description for the session and returns a new Net::SDP::Media object. The type parameter is optional, and will set the media type if specified.

Example:

        $time = $sdp->new_media_desc( 'audio' );

TODO

Stricter parsing of SDP, so that it can be used as a validator
Add support for Zone Adjustments (z=)

SEE ALSO

perl(1), Net::SAP

http://www.ietf.org/rfc/rfc2327.txt

BUGS

Please report any bugs or feature requests to bug-net-sdp@rt.cpan.org, or through the web interface at http://rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

AUTHOR

Nicholas J Humfrey, njh@cpan.org

COPYRIGHT AND LICENSE

Copyright (C) 2004 University of Southampton

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.005 or, at your option, any later version of Perl 5 you may have available.