/ 
WWW-Vox-1.1
/ WWW::Vox

NAME

WWW::Vox - Interact programmatically with Vox

SYNOPSIS

use WWW::Vox;
use WWW::Vox::Auth::Cookies;

my $cookie_auth = WWW::Vox::Auth::Cookies->new(
    cookies => { file => 'vox_cookies.txt' },
);
my $client = WWW::Vox->new( auth => $cookie_auth );

my ($tag_result) = $client->request('Tag.Autocomplete', { tag => 'foo' });
print @$tag_result;

my ($movie_result) = $client->search(
    type    => 'Video',
    conduit => 'Amazon',
    query   => 'foo',
    locale  => 'en_US',
);
my $movie_asset = $movie_result->create_asset();

DESCRIPTION

WWW::Vox provides a Perl interface to the Vox weblog service. Using instances of WWW::Vox as a client, one can manipulate assets in one's library.

INTERFACE

WWW::Vox->new(%params)

Creates a new, empty WWW::Vox client.

%params can contain:

  • auth

    The WWW::Vox::Auth object to use for authentication. The only provided authentication method is cookie authentication, provided by the WWW::Vox::Auth::Cookies module. Authentication modules can modify API requests at the JSON content and HTTP request levels to provide credentials to Vox; see WWW::Vox::Auth.

  • host

    The initial portion of the URI for the Vox instance your client will use. By default, this is set to http://www.vox.com, but you can override it by setting host appropriately. Note that you must include the http:// at the front, and that you don't need a / at the end. This option is provided for testing.

$vox->request($method, \%params)

Sends a JSON request for the Vox service to perform the task $method with parameters \%params. Other WWW::Vox modules and methods provide additional convenience over composing the JSON request yourself for the common actions they represent, but if necessary, you can roll your own.

$vox->search(%params)

Search in a conduit for an asset meeting certain criteria, returning a list of WWW::Vox::SearchResult objects. Required parameters are:

  • type

    The asset type for which to search. The searchable asset types are Photo, Book, Audio, and Video.

  • conduit

    The name of the conduit to search. The available conduits vary by asset type. Common conduits are Amazon (Book, Audio, and Video), Flickr (Photo), and YouTube (Video).

  • query

    The string with which to search. What this means varies by asset type and conduit. For example, when searching Amazon for a Movie, the query should be the movie's title.

Optional parameters are:

  • count

    The number of search results to return. The default is 10.

  • offset

    The number of search results to skip when retrieving this search's results. For example, to get the next "page" of results, repeat the search with offset incremented by the previous search's count parameter. The default is 0.

$vox->list_assets(%params)

Retrieves a number of assets saved in the authenticated user's library. Assets are returned as WWW::Vox::Asset instances. Required members of %params are:

  • type

    The type of the assets to list. Any Vox asset type is listable, including Photo, Book, Audio, Video, Link, Post, Comment, and Collection.

Other optional parameters are available to specify which set of assets to list. Optional members of %params are:

  • count

    The number of assets to return. By default, up to 20 assets are returned.

  • offset

    The number of assets to skip before returning assets. Increase this parameter by a previous call's count parameter to list the next "page" of assets. By default, no assets are skipped (that is, the first "page" is listed).

  • sort

    The field by which to sort the library when looking for the requested assets. By default, assets are sorted by issued (the date an asset was added to the user's library).

  • sort_dir

    The direction in which to sort assets. The value of this parameter should be either ascend or descend (which means newest first, for date fields). By default, the sorting direction is descend.

Note the combined defaults mean that, when all the optional fields are omitted, the 20 assets of the specified type most recently added to the user's library are returned.

$vox->retrieve_assets(@asset_ids)

Retrieves the WWW::Vox::Assets with the given asset IDs from the Vox service. Asset IDs are unique across all users and asset types, so you only need the ID.

$vox->retrieve_asset($asset_id)

Retrieves the WWW::Vox::Asset with the given asset ID from the Vox service. Asset IDs are unique across all users and asset types, so you only need the ID.

$vox->create_collection($name)

Creates a new collection, returning the WWW::Vox::Collection object for it.

DIAGNOSTICS

WWW::Vox produces errors as WWW::Vox::Error exceptions.

Error converting data to JSON text: message

request was not able to convert the \%data argument into a JSON formatted string. You may have passed in something other than a hash reference, or had an unserializable object or circular reference inside your data structure. See JSON for more on what data structures can be converted into JSON text.

The exception's perl_request hash member contains the \%data that caused an error.

HTTP error: code description

request was not able to send your request to Vox properly due to the given error using the HTTP protocol. You may not be able to currently reach Vox, or something about your request caused a server error.

The error's http_request and http_response hash members contain the involved HTTP::Request and HTTP::Response objects respectively.

Service error: message

request received an error from the Vox service. Your request may have been proper JSON and a proper request, but malformed. Check that you included all the necessary arguments for the method you invoked.

CONFIGURATION AND ENVIRONMENT

WWW::Vox requires no configuration files or environment variables.

DEPENDENCIES

WWW::Vox uses the CPAN modules Carp, JSON, and LWP.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-www-vox@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR

Mark Paschal <mark@sixapart.com>

LICENCE AND COPYRIGHT

Copyright 2006 Six Apart, Ltd. <cpan@sixapart.com>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.