.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::SDP 3"
.TH Net::SDP 3 "2008-01-13" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Net::SDP \- Session Description Protocol (rfc2327)
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Net::SDP;
.Ve
.PP
.Vb 1
\&  my $sdp = Net::SDP->new();
.Ve
.PP
.Vb 1
\&  $sdp->parse_file( 'myfile.sdp' );
.Ve
.PP
.Vb 3
\&  print "Session name: ".$sdp->session_name()."\en";
\&  print "Session info: ".$sdp->session_info()."\en";
\&  print "Session tool: ".$sdp->session_attribute('tool')."\en";
.Ve
.PP
.Vb 1
\&  $sdp->session_info( "This is my session" );
.Ve
.PP
.Vb 1
\&  print $sdp->generate();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Net::SDP\*(C'\fR is an \s-1SDP\s0 (Session Description Protocol) parser and generator. 
\&\f(CW\*(C`Net::SDP\*(C'\fR is object oriented and a single instance of \f(CW\*(C`Net::SDP\*(C'\fR represents
a single \s-1SDP\s0 session description. There are methods to easily get, set and create 
each of the fields in the session description.
.PP
The classes \f(CW\*(C`Net::SDP::Time\*(C'\fR and \f(CW\*(C`Net::SDP::Media\*(C'\fR are automatically instantiated 
for each Time Description (t=) and Media Description (m=).
.Sh "\s-1METHODS\s0"
.IX Subsection "METHODS"
.IP "\fBnew( [source] )\fR" 4
.IX Item "new( [source] )"
Creates a new \f(CW\*(C`Net::SDP\*(C'\fR session description object with default values for 
the required fields.
.Sp
If the optional paramater \f(CW\*(C`source\*(C'\fR is specified, then it is passed to 
\&\fIparse()\fR. If parsing fails, than \fInew()\fR will return undef.
.IP "\fBparse( source )\fR" 4
.IX Item "parse( source )"
Parses in an \s-1SDP\s0 description. This method tries to work our the source of the \s-1SDP\s0 data
automatically and is ideal for use with command line tools. The source may be 
a path to a file, a \s-1URL\s0, a \f(CW\*(C`Net::SAP::Packet\*(C'\fR object, \s-1SDP\s0 data itself or if undefined
 will be read in on \s-1STDIN\s0.
Returns 1 if successful, or 0 on failure.
.Sp
\&\fB\s-1NOTE:\s0\fR it is faster to pass \s-1SDP\s0 data straight into the \fInew()\fR method, as it does not 
then initialise the object with default values, this involves doing \s-1DNS\s0 lookups to
find out the name of the local host.
.IP "\fBparse_file( filepath )\fR" 4
.IX Item "parse_file( filepath )"
Parses in an \s-1SDP\s0 description from the specified file path. Returns 1 if successful, or 0 on failure.
.IP "\fBparse_url( url )\fR" 4
.IX Item "parse_url( url )"
Parses in an \s-1SDP\s0 description from the specified \s-1URL\s0. \s-1LWP\s0 (libwww\-perl) is required for this method. 
Returns 1 if successful, or 0 on failure.
.IP "\fB\f(BIparse_stdin()\fB\fR" 4
.IX Item "parse_stdin()"
Parses in an \s-1SDP\s0 description from \s-1STDIN\s0. Returns 1 if successful, or 0 on failure.
.IP "\fBparse_data( sdpdata )\fR" 4
.IX Item "parse_data( sdpdata )"
Parses the \s-1SDP\s0 description data passed as parameter. Returns 1 if successful, or 0 on failure.
.IP "\fB\f(BIgenerate()\fB\fR" 4
.IX Item "generate()"
Generates and returns \s-1SDP\s0 description. Note that you must have set the compulsory fields and have 
at least one Time Description for the \s-1SDP\s0 description to be valid.
.IP "\fB\f(BIsession_origin()\fB\fR" 4
.IX Item "session_origin()"
Get or Set the whole of the session origin field. \fB[o=]\fR
.Sp
Example:
.Sp
.Vb 2
\&        $origin = $sdp->session_origin();
\&        $sdp->session_origin( 'njh 3303643609 3303643669 IN IP4 152.78.104.83' );
.Ve
.IP "\fB\f(BIsession_origin_username()\fB\fR" 4
.IX Item "session_origin_username()"
Get or Set the username subfield of the session origin field. \fB[o=]\fR
.Sp
Example:
.Sp
.Vb 2
\&        $username = $sdp->session_origin_username();
\&        $sdp->session_origin_username( 'njh' );
.Ve
.IP "\fB\f(BIsession_origin_id()\fB\fR" 4
.IX Item "session_origin_id()"
Get or Set the \s-1ID\s0 subfield of the session origin field. This should be an \s-1NTP\s0 timestamp. \fB[o=]\fR
.Sp
Example:
.Sp
.Vb 2
\&        $id = $sdp->session_origin_id();
\&        $sdp->session_origin_id( 3303643609 );
.Ve
.IP "\fB\f(BIsession_origin_version()\fB\fR" 4
.IX Item "session_origin_version()"
Get or Set the version subfield of the session origin field. This should be an \s-1NTP\s0 timestamp. \fB[o=]\fR
.Sp
Example:
.Sp
.Vb 2
\&        $version = $sdp->session_origin_version();
\&        $sdp->session_origin_version( 3303643669 );
.Ve
.IP "\fB\f(BIsession_origin_net_type()\fB\fR" 4
.IX Item "session_origin_net_type()"
Get or Set the network type subfield of the session origin field. In most cases this will be '\s-1IN\s0'. \fB[o=]\fR
.Sp
Example:
.Sp
.Vb 2
\&        $net_type = $sdp->session_origin_net_type();
\&        $sdp->session_origin_net_type( 'IN' );
.Ve
.IP "\fB\f(BIsession_origin_addr_type()\fB\fR" 4
.IX Item "session_origin_addr_type()"
Get or Set the address type subfield of the session origin field. In most cases this will be '\s-1IP4\s0'. \fB[o=]\fR
.Sp
Example:
.Sp
.Vb 2
\&        $addr_type = $sdp->session_origin_addr_type();
\&        $sdp->session_origin_addr_type( 'IP6' );
.Ve
.IP "\fB\f(BIsession_origin_address()\fB\fR" 4
.IX Item "session_origin_address()"
Get or Set the address subfield of the session origin field. 
This may be a fully qualified domain name or global \s-1IP\s0 address but 
must not be a private \s-1IP\s0 or localhost. \fB[o=]\fR
.Sp
Example:
.Sp
.Vb 2
\&        $address = $sdp->session_origin_address();
\&        $sdp->session_origin_address( '152.78.104.83' );
.Ve
.IP "\fB\f(BIsession_identifier()\fB\fR" 4
.IX Item "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. \fB[o=]\fR
.Sp
Example:
.Sp
.Vb 1
\&        $ident = $sdp->session_identifier();
.Ve
.IP "\fB\f(BIsession_name()\fB\fR" 4
.IX Item "session_name()"
Get or Set the session name field. \fB[s=]\fR
.Sp
Example:
.Sp
.Vb 2
\&        $name = $sdp->session_name();
\&        $sdp->session_name( 'My Cool Session' );
.Ve
.IP "\fB\f(BIsession_info()\fB\fR" 4
.IX Item "session_info()"
Get or Set the session information/description field. \fB[i=]\fR
.Sp
Example:
.Sp
.Vb 2
\&        $name = $sdp->session_info();
\&        $sdp->session_info( 'Broadcast live from Southampton' );
.Ve
.IP "\fB\f(BIsession_uri()\fB\fR" 4
.IX Item "session_uri()"
Get or Set the session \s-1URI\s0 field. Used by \s-1WWW\s0 clients to get more information about the session. \fB[u=]\fR
.Sp
Example:
.Sp
.Vb 2
\&        $name = $sdp->session_uri();
\&        $sdp->session_uri( 'http://www.surgeradio.co.uk' );
.Ve
.IP "\fB\f(BIsession_email()\fB\fR" 4
.IX Item "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 \s-1ARRAYREF\s0.
This method will only return the first email address. \fB[e=]\fR
.Sp
Example:
.Sp
.Vb 3
\&        $email = $sdp->session_email();
\&        $sdp->session_email( 'njh@ecs.soton.ac.uk' );
\&        $sdp->session_email( ['njh@ecs.soton.ac.uk', 'njh@surgeradio.co.uk'] );
.Ve
.IP "\fB\f(BIsession_email_arrayref()\fB\fR" 4
.IX Item "session_email_arrayref()"
Returns all email addresses as an array reference. Will return an
empty \s-1ARRAYREF\s0 if no email addresses are available.
.IP "\fB\f(BIsession_phone()\fB\fR" 4
.IX Item "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 \s-1ARRAYREF\s0.
This method will only return the first phone number. \fB[p=]\fR
.Sp
Example:
.Sp
.Vb 3
\&        $phone = $sdp->session_phone();
\&        $sdp->session_phone( '+44 870 357 2287' );
\&        $sdp->session_phone( ['0870 357 2287', '41287'] );
.Ve
.IP "\fB\f(BIsession_phone_arrayref()\fB\fR" 4
.IX Item "session_phone_arrayref()"
Returns all phone numbers as an array reference. Will return an
empty \s-1ARRAYREF\s0 if no phone numbers are available.
.IP "\fBsession_key( method, [key] )\fR" 4
.IX Item "session_key( method, [key] )"
Get or Set the session encryption key field.
When setting the key parameter is optional \- dependant on the method. \fB[k=]\fR
.Sp
Example:
.Sp
.Vb 3
\&        ($method, $key) = $sdp->session_key();
\&        $sdp->session_key( 'prompt' );
\&        $sdp->session_key( 'base64', 'AoItAE8BAQ8DAQOBQwA' );
.Ve
.IP "\fBsession_attribute( name, [value] )\fR" 4
.IX Item "session_attribute( name, [value] )"
Get or Set an attribute for this session description. \fB[a=]\fR
.Sp
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 \s-1ARRAYREF\s0. If an attribute does not require it, 
then the value parameter is optional \- eg for 'recvonly' attribute.
.Sp
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 \s-1ARRAYREF\s0 is returned.
.Sp
Example:
.Sp
.Vb 2
\&        $tool = $sdp->session_attribute( 'tool' );
\&        $sdp->session_attribute( 'recvonly' );
.Ve
.IP "\fB\f(BIsession_attributes()\fB\fR" 4
.IX Item "session_attributes()"
Get a \s-1HASHREF\s0 of all the attributes associated with this session description \fB[a=]\fR
.Sp
Example:
.Sp
.Vb 1
\&        $hashref = $sdp->session_attributes();
.Ve
.IP "\fBsession_add_attribute( name, [value] )\fR" 4
.IX Item "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 \fB[a=]\fR
.Sp
Example:
.Sp
.Vb 2
\&        $audio->session_add_attribute( 'lang', 'en');
\&        $audio->session_add_attribute( 'lang', 'fr');
.Ve
.IP "\fBsession_del_attribute( name )\fR" 4
.IX Item "session_del_attribute( name )"
Deletes all attributes of given name.
Example:
.Sp
.Vb 1
\&        $audio->session_del_attribute( 'lang' );
.Ve
.IP "\fBmedia_desc_of_type( type )\fR" 4
.IX Item "media_desc_of_type( type )"
Returns the first media description (as a \f(CW\*(C`Net::SDP::Media\*(C'\fR) of the specified type.
.Sp
Example:
.Sp
.Vb 1
\&        $audio = $sdp->media_desc_of_type( 'audio' );
.Ve
.IP "\fBmedia_desc_arrayref( )\fR" 4
.IX Item "media_desc_arrayref( )"
Returns an \s-1ARRAYREF\s0 of all the media descriptions \- \f(CW\*(C`Net::SDP::Media\*(C'\fR objects.
.IP "\fB\f(BImedia_desc_delete_all()\fB\fR" 4
.IX Item "media_desc_delete_all()"
Deletes all media descriptors.
.ie n .IP "\fBmedia_desc_delete( \fB$num\fB )\fR" 4
.el .IP "\fBmedia_desc_delete( \f(CB$num\fB )\fR" 4
.IX Item "media_desc_delete( $num )"
Delete media description with index \f(CW$num\fR.
Returns 0 if successful or 1 on failure.
.IP "\fBtime_desc( [$num] )\fR" 4
.IX Item "time_desc( [$num] )"
Returns the time description with index number \f(CW$num\fR. 
Returns the first time description if, \f(CW$num\fR is undefined.
Return undef if no time description of chosen index is available.
Returns a \f(CW\*(C`Net::SDP::Time\*(C'\fR.
.IP "\fB\f(BItime_desc_arrayref()\fB\fR" 4
.IX Item "time_desc_arrayref()"
Returns an \s-1ARRAYREF\s0 of all the time descriptions \- \f(CW\*(C`Net::SDP::Time\*(C'\fR objects.
.IP "\fB\f(BItime_desc_delete_all()\fB\fR" 4
.IX Item "time_desc_delete_all()"
Deletes all time descriptors.
.ie n .IP "\fBtime_desc_delete( \fB$num\fB )\fR" 4
.el .IP "\fBtime_desc_delete( \f(CB$num\fB )\fR" 4
.IX Item "time_desc_delete( $num )"
Delete time description with index \f(CW$num\fR.
Returns 0 if successful or 1 on failure.
.IP "\fB\f(BInew_time_desc()\fB\fR" 4
.IX Item "new_time_desc()"
Creates a new time description for the session and returns a new \f(CW\*(C`Net::SDP::Time\*(C'\fR object.
.IP "\fBnew_media_desc( [type] )\fR" 4
.IX Item "new_media_desc( [type] )"
Creates a new media description for the session and returns a new \f(CW\*(C`Net::SDP::Media\*(C'\fR object.
The type parameter is optional, and will set the media type if specified.
.Sp
Example:
.Sp
.Vb 1
\&        $time = $sdp->new_media_desc( 'audio' );
.Ve
.SH "TODO"
.IX Header "TODO"
.IP "Stricter parsing of \s-1SDP\s0, so that it can be used as a validator" 4
.IX Item "Stricter parsing of SDP, so that it can be used as a validator"
.PD 0
.IP "Add support for Zone Adjustments (z=)" 4
.IX Item "Add support for Zone Adjustments (z=)"
.PD
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIperl\fR\|(1), Net::SAP
.PP
<http://www.ietf.org/rfc/rfc2327.txt>
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests to
\&\f(CW\*(C`bug\-net\-sdp@rt.cpan.org\*(C'\fR, 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.
.SH "AUTHOR"
.IX Header "AUTHOR"
Nicholas J Humfrey, njh@cpan.org
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2004 University of Southampton
.PP
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.