~ubuntu-branches/ubuntu/maverick/xmms2/maverick

#include "perl_xmmsclient.h"

MODULE = Audio::XMMSClient::Collection	PACKAGE = Audio::XMMSClient::Collection	PREFIX = xmmsv_coll_

=head1 NAME

Audio::XMMSClient::Collection - Media collections for Audio::XMMSClient

=head1 SYNOPSIS

  use Audio::XMMSClient;

  my $coll = Audio::XMMSClient::Collection->new('match', {
          artist => 'Solche',
  });

=head1 METHODS

=head2 new

=over 4

=item Arguments: $type, \%attributes?

=item Arguments: $type, %attributes?

=item Return Value: $collection

=back

  my $coll = Audio::XMMSClient::Collection->new('match', {
          artist => 'Solche',
  });

Create a new collection instance of type C<$type>. Also sets the
collections C<%attributes>, if given.

=cut

xmmsv_coll_t *
xmmsv_coll_new (class, type, ...)
		xmmsv_coll_type_t type
	PREINIT:
		int i, nargs;
		HV *args;
		HE *iter;
	CODE:
		RETVAL = xmmsv_coll_new (type);

		nargs = items - 2;
		if (nargs == 1) {
			if (!SvOK (ST (2)) || !SvROK (ST (2)) || !(SvTYPE (SvRV (ST (2))) == SVt_PVHV))
				croak ("expected hash reference or hash");

			args = (HV *)SvRV (ST (2));

			hv_iterinit (args);
			while ((iter = hv_iternext (args))) {
				xmmsv_coll_attribute_set (RETVAL, HePV (iter, PL_na), SvPV_nolen (HeVAL (iter)));
			}
		}
		else {
			if (nargs % 2 != 0)
				croak ("expected even number of attributes/values");

			for (i = 2; i <= nargs; i += 2) {
				xmmsv_coll_attribute_set (RETVAL, SvPV_nolen (ST (i)), SvPV_nolen (ST (i+1)));
			}
		}
	OUTPUT:
		RETVAL

=head2 parse

=over 4

=item Arguments: $pattern

=item Return Value: $collection

=back

  my $coll = Audio::XMMSClient::Collection->parse("artist:Solche +compilation");

Try to parse the given C<$pattern> to produce a collection structure.

=cut

xmmsv_coll_t *
xmmsv_coll_parse (class, const char *pattern)
	PREINIT:
		int ret;
	CODE:
		ret = xmmsv_coll_parse (pattern, &RETVAL);
	POSTCALL:
		if (RETVAL == 0)
			XSRETURN_UNDEF;
	OUTPUT:
		RETVAL

void
DESTROY (coll)
		xmmsv_coll_t *coll
	CODE:
		xmmsv_coll_unref (coll);

=head2 set_idlist

=over 4

=item Arguments: @ids

=item Return Value: none

=back

  $coll->set_idlist(qw/1 42 1337/);

Set the list of ids in the given collection. Note that the idlist is only
relevant for idlist collections.

=cut

void
xmmsv_coll_set_idlist (coll, ...)
		xmmsv_coll_t *coll
	PREINIT:
		int i;
		unsigned int *ids;
	INIT:
		ids = (unsigned int *)malloc (sizeof (unsigned int) * items);

		for (i = 0; i < items - 1; i++) {
			ids[i] = SvUV (ST (i + 1));
			if (ids[i] == 0) {
				free (ids);
				croak("0 is an invalid mlib id");
			}
		}

		ids[items - 1] = 0;
	C_ARGS:
		coll, ids
	CLEANUP:
		free (ids);

=head2 add_operand

=over 4

=item Arguments: $operand

=item Return Value: none

=back

  $coll->add_operand($other_coll);

Add the C<$operand> to a given collection.

=cut

void
xmmsv_coll_add_operand (coll, op)
		xmmsv_coll_t *coll
		xmmsv_coll_t *op

=head2 remove_operand

=over 4

=item Arguments: $operand

=item Return Value: none

=back

  $coll->remove_operand($other_coll);

Remove all the occurences of the C<$operand> in the given collection.

=cut

void
xmmsv_coll_remove_operand (coll, op)
		xmmsv_coll_t *coll
		xmmsv_coll_t *op

=head2 idlist_append

=over 4

=item Arguments: $id

=item Return Value: $success

=back

  my $success = $coll->idlist_append(5);

Append an C<$id> to the idlist.

=cut

int
xmmsv_coll_idlist_append (coll, id)
		xmmsv_coll_t *coll
		unsigned int id
	INIT:
		if (id == 0) {
			croak ("0 is an invalid mlib id");
		}

=head2 idlist_insert

=over 4

=item Arguments: $index, $id

=item Return Value: $success

=back

  my $success = $coll->idlist_insert(42, 2);

Insert an C<$id> at a given C<$index> in the idlist.

=cut

int
xmmsv_coll_idlist_insert (coll, index, id)
		xmmsv_coll_t *coll
		unsigned int index
		unsigned int id
	INIT:
		if (index > xmmsv_coll_idlist_get_size (coll)) {
			croak ("inserting id after end of idlist");
		}

		if (id == 0) {
			croak ("0 is an invalid mlib id");
		}

=head2 idlist_move

=over 4

=item Arguments: $from, $to

=item Return Value: $success

=back

  my $success = $coll->idlist_move(0, 3);

Move a value of the idlist to a new position.

=cut

int
xmmsv_coll_idlist_move (coll, from, to)
		xmmsv_coll_t *coll
		unsigned int from
		unsigned int to
	PREINIT:
		size_t idlist_len;
	INIT:
		idlist_len = xmmsv_coll_idlist_get_size (coll);

		if (from > idlist_len) {
			croak ("trying to move id from after the idlists end");
		}

		if (to >= idlist_len) {
			croak ("trying to move id to after the idlists end");
		}

=head2 idlist_clear

=over 4

=item Arguments: none

=item Return Value: $success

=back

  my $success = $coll->idlist_clear;

Empties the idlist.

=cut

int
xmmsv_coll_idlist_clear (coll)
		xmmsv_coll_t *coll

=head2 idlist_get_index

=over 4

=item Arguments: $index

=item Return Value: $value | undef

=back

  my $value = $coll->idlist_get_index(2);

Retrieves the value at the given C<$index> in the idlist.

=cut

NO_OUTPUT int
xmmsv_coll_idlist_get_index (xmmsv_coll_t *coll, unsigned int index, OUTLIST uint32_t val)
	INIT:
		PERL_UNUSED_VAR (targ);

		if (index > xmmsv_coll_idlist_get_size (coll)) {
			croak ("trying to get an id from behind the idlists end");
		}
	POSTCALL:
		if (RETVAL == 0)
			XSRETURN_UNDEF;

=head2 idlist_set_index

=over 4

=item Arguments: $index, $value

=item Return Value: $success

=back

  my $success = $coll->idlist_set_index(3, 1);

Sets the C<$value> at the given C<$index> in the idlist.

=cut

int
xmmsv_coll_idlist_set_index (coll, index, val)
		xmmsv_coll_t *coll
		unsigned int index
		uint32_t val
	PREINIT:
		size_t idlist_len;
	INIT:
		idlist_len = xmmsv_coll_idlist_get_size (coll);
		if (idlist_len == 0 || index > idlist_len - 1) {
			croak ("trying to set an id after the end of the idlist");
		}

=head2 idlist_get_size

=over 4

=item Arguments: none

=item Return Value: $size

=back

  my $size = $coll->idlist_get_size;

Get the size of the idlist.

=cut

size_t
xmmsv_coll_idlist_get_size (coll)
		xmmsv_coll_t *coll

=head2 get_type

=over 4

=item Arguments: none

=item Return Value: $type

=back

  my $type = $coll->get_type;

Return the type of the collection. Valid types are "reference", "union",
"intersection", "complement", "has", "equals", "match", "smaller", "greater",
"idlist", "queue", "partyshuffle".

=cut

xmmsv_coll_type_t
xmmsv_coll_get_type (coll)
		xmmsv_coll_t *coll

=head2 get_idlist

=over 4

=item Arguments: none

=item Return Value: @ids

=back

  my @ids = $coll->get_idlist;

Return the list of ids stored in the collection. Note that this must not be
confused with the content of the collection, which must be queried using
L<Audio::XMMSClient/coll_query_ids>.

=cut

void
xmmsv_coll_get_idlist (coll)
		xmmsv_coll_t *coll
	PREINIT:
		uint32_t *ret;
		size_t size;
		unsigned int i = 0;
	PPCODE:
		ret = xmmsv_coll_get_idlist (coll);

		if (ret == NULL)
			XSRETURN_UNDEF;

		size = xmmsv_coll_idlist_get_size (coll);
		EXTEND (sp, size);

		while (ret[i] != 0) {
			PUSHs (sv_2mortal (newSVuv (ret[i])));
			++i;
		}

=head2 operands

=over 4

=item Arguments: none

=item Return Value: @operands

=back

  my @operands = $coll->operands;

Get a list of operands of the collection.

=cut

void
operands (coll)
		xmmsv_coll_t *coll
	ALIAS:
		operand_list = 1
	PREINIT:
		xmmsv_t *operands_list;
		xmmsv_list_iter_t *it;
		xmmsv_t *value;
		xmmsv_coll_t *op;
	PPCODE:
		PERL_UNUSED_VAR (ix);

		operands_list = xmmsv_coll_operands_get (coll);

		for (xmmsv_get_list_iter (operands_list, &it);
		     xmmsv_list_iter_entry (it, &value);
		     xmmsv_list_iter_next (it)) {
			xmmsv_get_coll (value, &op);
			xmmsv_coll_ref (op);
			XPUSHs (sv_2mortal (perl_xmmsclient_new_sv_from_ptr (op, "Audio::XMMSClient::Collection")));
		}

		xmmsv_list_iter_explicit_destroy (it);

=head2 attribute_set

=over 4

=item Arguments: $key, $value

=item Return Value: none

=back

  $coll->attribute_set(field => 'artist');

Set an attribute C<$key> to C<$value> in the given collection.

=cut

void
xmmsv_coll_attribute_set (coll, key, value)
		xmmsv_coll_t *coll
		const char *key
		const char *value

=head2 attribute_remove

=over 4

=item Arguments: $key

=item Return Value: $success

=back 

  my $success = $coll->attribute_remove;

Remove an attribute C<$key> from the given collection. The return value
indicated whether the attribute was found (and removed).

=cut

int
xmmsv_coll_attribute_remove (coll, key)
		xmmsv_coll_t *coll
		const char *key

=head2 attribute_get

=over 4

=item Arguments: $key

=item Return Value: $value | undef

=back

  my $value = $coll->attribute_get('field');

Retrieve the C<$value> of the attribute C<$key> of the given collection. 

=cut

NO_OUTPUT int
xmmsv_coll_attribute_get (xmmsv_coll_t *coll, const char *key, OUTLIST char *val)
	INIT:
		PERL_UNUSED_VAR (targ);
	POSTCALL:
		if (RETVAL == 0)
			XSRETURN_UNDEF;

=head2 attribute_list

=over 4

=item Arguments: none

=item Return Value: %attributes

=back

  my %attributes = $coll->attributes_list;

Get a hash of all C<%attributes> of the given collection.

=cut

void
xmmsv_coll_attribute_list (xmmsv_coll_t *coll)
	PREINIT:
		xmmsv_dict_iter_t *it;
		const char *key;
		const char *value;
	PPCODE:
		xmmsv_get_dict_iter (xmmsv_coll_attributes_get (coll), &it);

		for (xmmsv_dict_iter_first (it);
		     xmmsv_dict_iter_valid (it);
		     xmmsv_dict_iter_next (it)) {

			xmmsv_dict_iter_pair_string (it, &key, &value);

			EXTEND (sp, 2);
			mPUSHp (key, strlen (key));
			mPUSHp (value, strlen (value));
		}

		xmmsv_dict_iter_explicit_destroy (it);

=head2 universe

=over 4

=item Arguments: none

=item Return Value: $collection

=back

  my $universe = Audio::XMMSClient::Collection->universe;

Returns a collection referencing the whole media library, i.e. the "All Media"
collection.

=cut

xmmsv_coll_t *
xmmsv_coll_universe (class="optional")
	C_ARGS:
		/* void */

=head1 AUTHOR

Florian Ragwitz <rafl@debian.org>

=head1 SEE ALSO

L<Audio::XMMSClient>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2006-2008, Florian Ragwitz

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

=cut

BOOT:
	PERL_UNUSED_VAR (items);