File: Client.pm

package info (click to toggle)
libmusicbrainz-client-perl 0.11-2
  • links: PTS
  • area: main
  • in suites: etch, etch-m68k
  • size: 172 kB
  • ctags: 150
  • sloc: perl: 532; makefile: 57; pascal: 38
file content (475 lines) | stat: -rw-r--r-- 12,366 bytes parent folder | download | duplicates (4)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
package MusicBrainz::Client;
# --------------------------------------------------------------------------
#
#   MusicBrainz::Client -- The Internet music metadatabase
#
#   Copyright (C) 2003-2006 Alexander van Zoest
#   
#   $Id: Client.pm 8065 2006-07-03 22:49:35Z svanzoest $
#
#----------------------------------------------------------------------------*/

use 5.006_001; 
use strict;
use warnings;
use Carp;

require Exporter;
require DynaLoader;
use AutoLoader;

our @ISA = qw(Exporter);

# Items to export into callers namespace by default. Note: do not export
# names by default without a very good reason. Use EXPORT_OK instead.
# Do not simply export all your public functions/methods/constants.

# This allows declaration	use MusicBrainz::Client ':all';
# If you do not need this, moving things directly into @EXPORT or @EXPORT_OK
# will save memory.
our %EXPORT_TAGS = ( 'all' => [ qw(MB_CDINDEX_ID_LEN MB_ID_LEN
) ] );

our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );

our @EXPORT = qw(
);

our $VERSION = 0.11;


sub AUTOLOAD {
    # This AUTOLOAD is used to 'autoload' constants from the constant()
    # XS function.

    my $constname;
    our $AUTOLOAD;
    ($constname = $AUTOLOAD) =~ s/.*:://;
    croak "&MusicBrainz::Client::constant not defined" if $constname eq 'constant';
    my ($error, $val) = constant($constname);
    if ($error) { croak $error; }
    {
        no strict 'refs';
        # Fixed between 5.005_53 and 5.005_61
#XXX    if ($] >= 5.00561) {
#XXX        *$AUTOLOAD = sub () { $val };
#XXX    }
#XXX    else {
            *$AUTOLOAD = sub { $val };
#XXX    }
    }
    goto &$AUTOLOAD;
}

require XSLoader;
XSLoader::load('MusicBrainz::Client', $VERSION);

# Preloaded methods go here.

# Autoload methods go after =cut, and are processed by the autosplit program.

1;
__END__


=head1 NAME

MusicBrainz::Client - MusicBrainz Client API

=head1 SYNOPSIS

  use MusicBrainz::Client;
  use MusicBrainz::Queries qw(:all);

  my $mb = MusicBrainz::Client->new(); 
  if(! $mb->query_with_args( MBQ_FindArtistByName, [ "Pink Floyd" ]) ) {
    die("Query failed: ", $mb->get_query_error(), "\n");
  }
  print "Found ", $mb->get_result_int(MBE_GetNumArtists), " artists\n";

=head1 DESCRIPTION

This module provides access to the musicbrainz client API using a perl-ish
OO interface.

=head2 Methods
  

=over 4


=item new

$mb->new();

Create a new handle to the MusicBrainz object.

=item get_version

($major, $minor, $revision) = $mb->get_version();

Get the version number of the libmusicbrainz library in use.

=item set_server

$success = $mb->set_server($serverAddr, $serverPort);

Set the name and the port of the MusicBrainz server to use.
If this function is not called, the default www.musicbrainz.org server on port 80 will be used.

See also: L<set_proxy>

=item set_debug

$mb->set_debug($debug);

Enable debug out to stdout by sending a non-zero value to this function.


=item set_proxy

$success = $mb->set_proxy($serverAddr, $serverPort);

Set the name of the HTTP Proxy to use.
This function must be called anytime the client library must communicate via a proxy firewall.

See also: L<set_server>


=item authenticate

$success = $mb->authenticate($userName, $password);

This function must be called if you want to submit data to the server 
and give the user credit for the submission. If you're looking up data 
from the server, you do not need to call authenticate. If you are 
submitting data to the MB server and you want your submissions be submitted 
anonymously, then do not call this function.

returns true if the server authentication was correctly initiated.

Note: the password is sent in plaintext.


=item set_device

$success = $mb->set_device($device);

Call this function to set the CD-ROM drive device if you plan to use the 
client library to identify and look up CD-ROMs using MusicBrainz. 
Unix: specify a device such as /dev/cdrom. Defaults to /dev/cdrom 
Windows: specify a drive letter of a CD-ROM drive. e.g. E:

Always returns true.


=item use_utf8

$mb->use_utf8( 1 );

Use this function to set the output returned by the Get function. 
The Get functions can return data in ISO-8859-1 encoding or in UTF-8. 
Defaults to ISO-8859-1.

=item set_depth

$mb->set_depth($depth);
 
Set the search depth of the query. 
Please refer to the "Query Depth" section in the MusicBrainz HOWTO 
(http://www.musicbrainz.org/client_howto.html) for an explanation of this value. 
Defaults to 2.

=item set_max_items

$mb->set_max_items($maxItems);

Set the maximum number of items to return to the client. 
If a search query yields more items than this max number, 
the server will omit the excess items and not return them to the client. 
This value defaults to 25.

See also: L<query>

=item query

$success = $mb->query($rdfObject);

Query the MusicBrainz server. 
Use this function if your query requires no arguments other than the query itself. 
Please refer to the MusicBrainz::Queries module for the documentation 
on the available queries.

Returns true if the query succeeded (even if no items are returned) 
and false if the query failed. 
Call $mb->get_query_error(); for details on the error that occurred.
 
 See also: L<get_query_error> , L<query_with_args>
 

=item query_with_args
 

$sucess = $mb->query_with_args($rdfObject, \@args);

Query the MusicBrainz server. 
Use this function if your query requires one or more arguments. 
The arguments are as an anonymous array.

$rdfObject is one of the exportable constants defined in MusicBrainz::Queries
  
Returns true if the query succeeded (even if no items are returned) 
and false if the query failed. 
Call $mb->get_query_error(); for details on the error that occurred.
  
See also: L<get_query_error> , L<query>
  

=item get_web_submit_url
  

$url = $mb->get_web_submit_url();
  
Use this function to query the current CD-ROM and to calculate the web 
submit URL that can be opened in a browser in order to start the web 
based CD-ROM Submission to MusicBrainz. The CD-ROM in the CD-ROM drive 
set by $mb->set_device(); will be queried.
  
Returns true if the url was successfully generated, false if an error occurred.
  
See also: L<set_device>
  

=item get_query_error
  

$error = $mb->get_query_error();
  
Retrieve the error message that was generated during the last call 
to $mb->query(); or $mb->query_with_args();
  
See also: L<query> , L<query_with_args>
  

=item select
  

$success = $mb->select($selectQuery);
  
Select a context in the result query. Use this function if your Select requires 
no ordinal arguments. Pass this function a select query (starts with MBS_) from MusicBrainz::Queries. 
Please refer to the MusicBrainz HOWTO (http://www.musicbrainz.org/client_howto.html)
for more details on why you need to do a Select and what types of Selects are available. 
  
Returns true if the select succeeded, false otherwise.
  
See also: L<select1> 
  

=item select1
  

$success = $mb->select1($selectQuery, $ord);
  
Select a context in the result query. Use this function if your Select 
requires one ordinal argument. Pass this function a selectQuery 
(usually start with MBS_) from MusicBrainz::Queries.
Please refer to the MusicBrainz HOWTO (http://www.musicbrainz.org/client_howto.html)
for more details on why you need to do a Select and what types of Selects are available. 
  
Returns true if the select succeeded, false otherwise. 
  
See also: L<select>
  

=item get_result_data
  

$data = $mb->get_result_data($resultName);
  
Extract a piece of information from the data returned by a successful query. 
This function takes a resultName (usually named starting with MBE_) from MusicBrainz::Queries.
Please refer to the MusicBrainz HOWTO (http://www.musicbrainz.org/client_howto.html)
  
Returns true if the correct piece of data was returned and found, false otherwise.
  
See also: L<get_result_data1>
  

=item get_result_data1


$data1 = $mb->get_result_data1($resultName, $ordinal);

Extract a piece of information from the data returned by a successful query. 
This function takes a resultName (usually named starting with MBE_) from MusicBrainz::Queries.
See the MusicBrainz HOWTO (http://www.musicbrainz.org/client_howto.html).
$ordinal is the position of the data you wish to retrieve.

Returns true if the correct piece of data was returned and found, false otherwise.

See also: L<get_result_data> 


=item does_result_exist


$success = $mb->does_result_exist($resultName);

Check to see if a piece of information exists in data returned by a successful query. 
This function takes the same resultName argument as L<get_result_data>

Returns true if the result data exists, false otherwise 

See also: L<get_result_data> 
  

=item does_result_exist1


$success $mb->does_result_exist1($resultName, $ordinal);

Check to see if a piece of information exists in data returned by a 
successful query. This function takes the same resultName and ordinal 
arguments as L<get_result_data1>

Returns true if the result data exists, false otherwise 

See also: L<get_result_data1> 


=item get_result_int


$result = $mb->get_result_int($resultName);

Return the integer value of a result from the data returned 
by a successful Query. This function takes the same resultName 
argument as L<get_result_data>

Returns the integer value of the result 

See also: L<get_result_data> 


=item get_result_int1


$result = $mb->get_result_int1($resultName, $ordinal);

Return the integer value of a result from the data returned 
by a successful Query. This function takes the same resultName and ordinal
arguments as L<get_result_data1>

Returns the integer value of the result 

See also: L<get_result_data1>


=item get_result_rdf


$rdfstr = $mb->get_result_rdf();

Retrieve the RDF that was returned by the server. 
Most users will not want to use this function!


=item set_result_rdf


$success = $mb->set_result_rdf($rdfstr);

Set an RDF object for so that the Get functions can be used to 
extract data from the RDF. Advanced users only!

See also: L<get_result_rdf>


=item get_id_from_url


$id = $mb->get_id_from_url($url);

Extract the actual artist/album/track ID from a MBE_GETxxxxxId query. 
The MBE_GETxxxxxId functions return a URL to where the more RDF metadata 
for the given ID can be retrieved. Callers may wish to extract only the 
ID of an artist/album/track for reference elsewhere.

See also: L<get_result_data>


=item get_fragment_from_url


$fragment = $mb->get_fragment_from_url($url);

Extract the identifier fragment from a URI. Given a URI this function will 
return the string that follows the # seperator. 
(e.g. when passed 'http://musicbrainz.org/mm/mq-1.1#ArtistResult', this function
will return 'ArtistResult' 
  

=item get_ordinal_from_list


$ord = $mb->get_ordinal_from_list($listType, $URI);

Get the ordinal (list position) of an item in a list. 
This function is normally used to retrieve the track number out 
of a list of tracks in an album using a list query (usually MBE_AlbumGetTrackList)

See also: MBE_AlbumGetTrackList in MusicBrainz::Queries


=item get_mp3_info


($duration, $bitrate, $stereo, $samplerate) =  $mb->get_mp3_info($filename);

This helper function calculates the crucial pieces of information for a
MP3 files. $duration = duration of the MP3 in milliseconds, which is handy for 
passing the length of the track to the TRM generation routines. Beware: The 
TRM routines are expecting the duratin in SECONDS, so you will need to divide the 
duration returned by this function by 1000 before you pass it to the TRM routines.

=back

=head2 Windows Platform

Since this module makes use of Sockets, be sure to call $mb->WSAInit() and $mb->WSAStop().
  
=head2 Examples

For examples on how to use this API please see the test scripts provided and the
C client library documentation at http://www.musicbrainz.org/client_howto.html

=head2 EXPORT

None by default.

=head2 Exportable constants

  MB_CDINDEX_ID_LEN
  MB_ID_LEN

=head1 SEE ALSO

  MusicBrainz::Queries
  MusicBrainz::TRM
  http://www.musicbrainz.org/client_howto.html
  http://www.musicbrainz.org/
  perl(1) 

=head1 AUTHOR

Sander van Zoest <svanzoest@cpan.org>

=head1 COPYRIGHT AND LICENSE

Copyright 2003-2006 by Alexander van Zoest.

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

=cut