/ 
Net-SDP-0.03
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().

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.

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 IN4 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_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_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');
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.

time_desc()

Returns the first time description (as a Net::SDP::Time).

time_desc_arrayref()

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

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

Deal with multiple email / phone numbers better (e=) (p=)
Add support for Zone Adjustments (z=)
Net::SDP::Time doesn't handle (r=) Repeat Time Field
Deleting and adjusting stuff like attributes

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 Humfrey, njh@ecs.soton.ac.uk

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.