doc/man3/Quvi.pod

   1 =head1 NAME
   2
   3 WWW::Quvi - Perl extension interface for libquvi
   4
   5 =head1 SYNOPSIS
   6
   7   use WWW::Quvi;
   8   my $q = new WWW::Quvi::Query;
   9   my $m = $q->parse($url);
  10   croak "error: $q->{errmsg}" unless $q->{ok};
  11
  12 =head1 DESCRIPTION
  13
  14 WWW::Quvi provides a Perl interface to libquvi, a small C library for
  15 parsing Flash media stream URLs. It is written in C++ and uses SWIG to
  16 connect to the libquvi API.
  17
  18 =head1 DOCUMENTATION
  19
  20 This module provides a Perl interface to libquvi. This documentation
  21 contains the Perl specific details and some sample code. The libquvi
  22 documentation should be consulted for the API details at
  23 L<http://quvi.sourceforge.net/>.
  24
  25 =head1 WWW::Quvi::version
  26
  27 A wrapper function that returns WWW::Quvi version and libquvi version
  28 information.
  29
  30   WWW::Quvi::version;                           # Module version
  31   WWW::Quvi::version(WWW::Quvi::ModuleVersion); # Ditto.
  32   WWW::Quvi::version(WWW::Quvi::libquviVersion);
  33   WWW::Quvi::version(WWW::Quvi::libquviVersionLong);
  34
  35 =head1 WWW::Quvi::Options
  36
  37 A container hash for the options used with libquvi that would normally
  38 (using the C API) be set with C<quvi_setopt(3)>.
  39
  40   $opts->{verbose_libcurl} = 1;                    # Default: 0
  41   $opts->{user_agent}      = 'Foo/1.0';            # Default: ""
  42   $opts->{http_proxy}      = 'http://foo:1234';    # Default: ""
  43   $opts->{category}        = WWW::Quvi::ProtoHttp; # Default: ProtoAll
  44   $opts->{resolve}         = 0;                    # Default: 1
  45   $opts->{format}          = 'best';               # Default: "default"
  46   $opts->{verify}          = 0;                    # Default: 1
  47
  48 =head1 WWW::Quvi::Media
  49
  50 A container hash that holds the parsed media details accessible using
  51 C<quvi_getprop(3)>.
  52
  53   $media->{content_length}  # Content length as returned by the server
  54   $media->{thumbnail_url}   # Thumbnail URL (if any)
  55   $media->{content_type}    # Content-type as returned by the server
  56   $media->{file_suffix}     # File suffix parsed from the content-type
  57   $media->{start_time}      # Start time for media (if any)
  58   $media->{page_title}      # Media title
  59   $media->{page_url}        # Page URL
  60   $media->{duration}        # Duration in msec (if any)
  61   $media->{host}            # Host string
  62   $media->{url}             # Media stream URL
  63   $media->{id}              # Media ID
  64
  65 =head1 WWW::Quvi::Query
  66
  67 =over 4
  68
  69 =item parse($url)  [function]
  70
  71 Parse media details for URL. Returns WWW::Quvi::Media object.
  72
  73   my $m = $q->parse($url);
  74
  75 =item ($domain, $formats) next_website()  [function]
  76
  77 Return next supported website (domain, formats). These values are
  78 returned by the libquvi webscripts.
  79
  80 Note that C<formats> no practical use since libquvi 0.2.17. This
  81 function is most useful for listing the available support.
  82
  83 Use the C<formats> function (below) instead if you need to know which
  84 formats are available to an URL.
  85
  86   while ($q->{ok}) {
  87     my ($d,$f) = $q->next_website;
  88     say "$d\t$f" if $q->{ok};
  89   }
  90
  91 =item formats($url)  [function]
  92
  93 Returns a string containing a list of available formats to an URL. Each
  94 format ID is separated by a pipe character.
  95
  96   my $fmts = $q->formats($url);
  97   croak "error: $q->{errmsg}" unless $q->{ok};
  98   say $_ foreach (split /\|/, $fmts);
  99
 100 =item set_opts($opts)  [function]
 101
 102 Set Query options (see also L</WWW::Quvi::Options>).
 103
 104 =item supported($url)  [function]
 105
 106 Returns a non-zero value if the URL is not supported.
 107
 108 This is a networkless check meaning that it will return
 109 WWW::Quvi::NoSupport for most shortened (or compressed) URLs.
 110
 111 If your application must support such URLs, use Query::parse
 112 instead and make sure you have not set 'resolve' to 0 (disable)
 113 in your L</WWW::Quvi::Options>.
 114
 115 =item ok  [variable]
 116
 117 Non-zero if an error occurred.
 118
 119 =item errmsg  [variable]
 120
 121 Last error message. Check L</ok> flag for errors.
 122
 123   croak $q->{errmsg} unless $q->{ok};
 124
 125 =item quvi_code  [variable]
 126
 127 Last libquvi returned code.
 128
 129 =item resp_code  [variable]
 130
 131 Last response (assumed HTTP) code returned by the server.
 132
 133 =back
 134
 135 =head1 RETURN CODES (WWW::Quvi::*)
 136
 137 L</WWW::Quvi::Query> saves the last libquvi returned code as
 138 C<quvi_code>. In most cases, it is sufficient to just check
 139 the C<ok> and use the C<errmsg> instead.
 140
 141   OK                # No error
 142   Mem               # Memory allocation error
 143   BadHandle         # Bad handle
 144   InvArg            # Invalid function argument
 145   CurlInit          # libquvi initialization failure
 146   Last              # Last element in the list
 147   AbortedByCallBack # Aborted by a callback function
 148   LuaInit           # liblua initialization failure
 149   NoLuaWebsite      # Failed to find any libquvi webscripts
 150   NoLuaUtil         # Failed to find the libquvi utility scripts
 151   NoSupport         # libquvi cannot handle the URL
 152   CallbackError     # Network callback error occurred
 153   IconvError        # libiconv error occurred
 154   LuaError          # liblua (or webscript) error occurred
 155
 156 Note that L</WWW::Quvi::Query> saves the last server returned
 157 B<HTTP code> as C<resp_code>. This documentation does not cover
 158 the I<HTTP codes>.
 159
 160 =head1 PROTOCOL CATEGORIES (WWW::Quvi::*)
 161
 162 The protocol category defines which of the webscripts, that libquvi
 163 provides, your application is interested in.
 164
 165 For example, if your application can handle only HTTP connections,
 166 then it would make sense to set the C<category> (see
 167 L</WWW::Quvi::Options>) to C<ProtoHttp>.
 168
 169   ProtoHttp     # Protocol category HTTP
 170   ProtoMms      # ...
 171   ProtoRtsp     # ...
 172   ProtoRtmp     # ...
 173   ProtoAll      # Any of the above categories
 174
 175 =head1 NOT IMPLEMENTED
 176
 177 =over 4
 178
 179 =item B<quvi_supported_ident at al>
 180
 181 =item B<Linked list interface>
 182
 183 =item B<Network interface>
 184
 185 =item B<Media segments>
 186
 187 =item B<Callbacks>
 188
 189 =back
 190
 191 =head1 WWW
 192
 193  Home  : <http://www-quvi.sourceforge.net/>
 194  gitweb: <http://repo.or.cz/w/www-quvi.git>
 195
 196 =head1 LICENSE
 197
 198 WWW::Quvi is free software, licensed under the LGPLv2.1+.
 199
 200 =head1 SEE ALSO
 201
 202 C<quvi(1)>
 203
 204 =head1 AUTHOR
 205
 206 Toni Gundogdu <legatvs at sign gmail com>